@godaddy/gd-commerce-storefront 0.5.0 → 0.7.0

package/README.md

@@ -55,11 +55,14 @@ Use the providers your application already has; do not create another router or
 | `productPath` | `/products` | Same-origin prefix for product links; register `${productPath}/:productId` |
 | `checkoutSuccessPath` | unset | Same-origin return route; enables checkout UI only when supplied |
 | `onItemAdded` | unset | Called with `{ name, quantity, isSample }` after each add, live or sample; use it to confirm adds on a site with a cart page instead of a drawer |
+| `onEvent` | unset | Called with a [`CommerceEvent`](#events) for every cart change and failure, such as for analytics |
+| `locale` | `en-US` | BCP 47 locale for formatting prices, such as `de-DE`; an invalid tag falls back to `en-US` with a development warning. It never selects UI text |
 | `theme` | inherited text and transparent wrappers; neutral control palette | CSS custom properties applied to storefront surfaces and the portalled drawer |
+| `getSwatch` | unset | Swatches for attribute values, such as colors. Returns a CSS `background` for a value, or nothing. See [swatches](#swatches) |
 
 Provide root-relative paths without a trailing slash. Enable `checkoutSuccessPath` only after your server supports checkout and validates merchant readiness. Mount a corresponding return page. A redirect back from checkout is **not proof of payment**; that page must obtain authoritative payment status from your server. This package does not provide a payment receipt page or merchant onboarding.
 
-`GET /api/commerce/config` supplies the currency and opaque cart scope. The scope must change when the store, channel, or currency binding changes. The draft-order cart displays its subtotal and explains that shipping, taxes, and discounts are calculated at checkout. The explanation's outer element has the stable `commerce-cart-checkout-adjustments-note` class so applications can hide it when needed. The cart does not create a checkout session or calculate adjustments. Applications do not pass store IDs or credentials into the browser package. One storefront binding is supported per page and query client.
+`GET /api/commerce/config` supplies the currency and opaque cart scope. The scope must change when the store, channel, or currency binding changes. The draft-order cart displays its subtotal and a row saying that shipping, taxes and discounts are calculated at checkout. The explanation's outer element has the stable `commerce-cart-checkout-adjustments-note` class so applications can hide it when needed. The cart does not create a checkout session or calculate adjustments. Applications do not pass store IDs or credentials into the browser package. One storefront binding is supported per page and query client.
 
 A connection failure leaves the surrounding application and its state mounted. Catalog and product surfaces show the connection error and retry action. Custom integrations can render `CommerceStatus` or inspect `useCommerce().connection`.
 
@@ -76,6 +79,8 @@ A connection failure leaves the surrounding application and its state mounted. C
     '--commerce-surface': '#ffffff',
     '--commerce-text': '#171717',
     '--commerce-radius': '0.75rem',
+    '--commerce-sale': '#b42318',
+    '--commerce-on-sale': '#ffffff',
   }}
 >
   {/* Register /collection and /item/:productId in your router. */}
@@ -85,9 +90,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. Internal utility class names and markup are not a customization API; use the [product](#custom-product-layouts), [catalog](#custom-catalog-layouts) and [cart](#custom-cart-layouts) parts to change a layout.
+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. Muted text, hairlines, image placeholders and the quieter outlined buttons (cart button, product card actions, pagination) derive from the inherited text color, so they read on a light or dark page without configuration. `--commerce-surface` colors form inputs and the opaque cart drawer, paired with `--commerce-text`; it does not color component wrappers. Error and warning messages bring their own light background. The Sale badge fills with `--commerce-sale` behind `--commerce-on-sale` text, so it reads over an image and on any page; sale prices keep the surrounding text color, with the compare-at price struck through beside them. Images have square corners; `--commerce-radius` rounds buttons, inputs and option buttons. Primary buttons use `--commerce-accent` and are ringed in it on focus, so choose an accent that contrasts with the page. 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](#custom-product-layouts), [catalog](#custom-catalog-layouts) and [cart](#custom-cart-layouts) parts to change a layout, and the [styling hooks](#styling-hooks) to style inside a part.
 
-The first release uses English UI text and `en-US` currency formatting. The catalog title and description are configurable through `CatalogHeader`. Full localization is outside this initial API.
+Prices follow the provider's `locale`, which defaults to `en-US`. UI text is English. The catalog title and description are configurable through `CatalogHeader`, and many parts take [replacement text](#replacing-text). Full localization is outside this initial API. When it arrives, translated text will be a separate prop that a site opts into; `locale` will keep formatting only, so a site that sets it for prices never gets new wording in a minor release. Replacement text will still take priority over translations.
 
 ## Compatibility
 
@@ -100,17 +105,20 @@ The repository example uses React Router 7. Follow each router version's own Rea
 | Export | Purpose |
 | --- | --- |
 | `CommerceStorefront` | Recommended integration: provider and one drawer |
-| `Catalog` | Six products per cursor page. Its `title`, `description`, and `showHeader` props are deprecated; compose `CatalogRoot` instead |
+| `Catalog` | Six products per cursor page, or `pageSize`. Its `title`, `description`, and `showHeader` props are deprecated; compose `CatalogRoot` instead |
 | `CatalogRoot` and catalog parts | Build a [custom catalog or card layout](#custom-catalog-layouts) with the same rules as `Catalog` |
-| `ProductDetails` | Reads `:productId`; validates URL option selections against catalog results |
+| `ProductDetails` | Reads `:productId`; validates URL option selections against catalog results. `ProductDetailsRoot` also takes a `productId` prop |
 | `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; `ProductCardRoot` and card parts customize it |
+| `RelatedProducts` | Optional: other products from the catalog's first page, for after the product page. See [related products](#related-products) |
 | `CartDrawer` | The cart dialog; `CommerceStorefront` mounts one |
 | `CartDrawerRoot`, `CartRoot` and cart parts | Build a [custom drawer or a cart page](#custom-cart-layouts) with the same rules as `CartDrawer` |
-| `CartButton` | Opens the shared drawer and displays item count; `useCart()` builds a custom one |
-| `AddToCartButton` | Adds a verified `sku`, `name`, and optional integer `quantity`; while disabled, its accessible description says why |
+| `CartButton` | Opens the shared drawer: a bag icon with a count badge, named "Cart, 2 items". Its children replace the icon with a label, and `useCart()` builds a custom one |
+| `AddToCartButton` | Adds a verified `sku`, `name`, and optional integer `quantity`; while disabled, its accessible description says why. Its children replace the label |
 | `CommerceStatus` | Connection progress/error/retry for custom layouts |
 | `useCommerce` | Cart, connection, pending/error state and serialized cart actions |
+| `useMoney` | Formats minor units in the provider's `locale`, like the package's own prices, for custom parts |
+| `ProductImage` | A product image with the package's placeholder for a missing or broken image, for custom parts |
 | `CommerceProvider` | Lower-level composition when the recommended wrapper does not fit, such as a custom drawer; mount it once |
 
 The package exports TypeScript catalog/cart response types and selection/summary helpers for custom product layouts. `useCommerce` actions return `Promise<boolean>`: `false` means an operation failed or its connection became stale. Inspect `error` for active-session failures. Do not automatically retry a failed mutation: the server may have committed it before the response failed. `applyDiscount(code)` is available to custom layouts; the default drawer does not render a promotion form.
@@ -119,43 +127,66 @@ The package exports TypeScript catalog/cart response types and selection/summary
 
 ## 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:
+`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`, or its `productId` prop, 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,
+  ProductDetailsBackLink, ProductDetailsBadge, 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'>
+  <ProductDetailsBackLink className='mb-4 sm:mb-6' />
+  <div className='grid items-start gap-8 md:grid-cols-[minmax(0,1.15fr)_minmax(0,1fr)] lg:gap-12'>
+    <div className='relative min-w-0'>
+      <ProductDetailsGallery />
+      <ProductDetailsBadge className='pointer-events-none absolute left-4 top-4' />
+    </div>
+    <div className='min-w-0 md:pt-2'>
       <ProductDetailsTitle />
-      <ProductDetailsPrice className='mt-6' />
-      <ProductDetailsDescription className='my-8' />
-      <ProductDetailsPurchase className='border-t border-neutral-200 pt-8' />
+      <ProductDetailsPrice className='mt-2' />
+      <ProductDetailsDescription className='mt-6' />
+      <ProductDetailsPurchase className='mt-6 border-t border-commerce-line pt-6' />
     </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.
+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. `border-commerce-line` and `divide-commerce-line` stand for the package's hairline, the surrounding text color at 14% opacity, which reads on light and dark pages alike; use your own border color in its place.
 
-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:
+Add your own elements between parts, reorder them, or leave out display parts. `ProductDetailsBadge` shows "Sale" when the verified SKU's compare-at price is above its price, or before then when some SKU's compare-at price is above that SKU's own price, and nothing otherwise. `ProductDetailsPrice` shows "From" and the starting price until a SKU is verified. It strikes through a compare-at price beside it only when the cheapest SKUs all have that compare-at price, so a strike-through never pairs one SKU's price with another's compare-at price. `ProductDetailsPurchase` renders the options and status, then the quantity and add button in one row, then the availability. 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. The quantity shows a message when it cannot be added, such as more than the stock |
-| `ProductDetailsAddToCart` | Adds the verified SKU and quantity; before a SKU is verified, its accessible description gives the reason |
+| `ProductDetailsOptions` | A control for every attribute, or the SKU list for products without attributes |
+| `ProductDetailsOption` | One attribute, by `attribute` name, as a group of buttons (radios); as swatches when [`getSwatch`](#swatches) gives every value one; or as a select when it has more than eight values. Nothing when the product lacks it |
+| `ProductDetailsPurchaseStatus` | The one message explaining why a full selection is not purchasable, such as an unavailable combination; nothing when ready or before every option is chosen |
+| `ProductDetailsQuantity` | A quantity stepper, capped at the verified SKU's stock and disabled when it is sold out. It shows a message when a typed quantity cannot be added |
+| `ProductDetailsAvailability` | Stock for the verified SKU; nothing before verification |
+| `ProductDetailsAddToCart` | Adds the verified SKU and quantity, labeled with the total, such as "Add to cart · $64.00". Until every option is chosen it names the next one, such as "Select size", and pressing it shows an error on each missing option and focuses the first. While a selection is checked or unavailable, it is disabled and its accessible description gives the reason |
+
+Values whose SKUs are all sold out, given the shopper's other selections, are crossed out and announced as "sold out", but stay selectable, so the shopper can change options in any order. This needs every SKU with its attribute values in the product response, which `@godaddy/gd-commerce-server` returns for up to 50 SKUs; for a product with more, no value is marked, and the add button still says "Out of stock" once a sold-out SKU is chosen.
 
 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.
+The root keeps the selection in the page URL, as `option.<attribute>` and `sku`, so a reload or a shared link keeps it. To show a product outside its route, such as in a quick view or next to another product, pass `productId` and set `urlState={false}`. That root keeps its selection to itself, and it ends when the root unmounts. Give every root but one on a page `urlState={false}`; otherwise the roots share one selection. A root with no `productId` on a route without `:productId` shows the not-found state and, in development builds, warns.
+
+```tsx
+{/* Your own dialog, opened from a card with the product's ID. */}
+<QuickViewDialog open={quickViewId !== null} onClose={() => setQuickViewId(null)}>
+  {quickViewId && (
+    <ProductDetailsRoot productId={quickViewId} urlState={false} loading={<p role='status'>Loading…</p>}>
+      <ProductDetailsTitle />
+      <ProductDetailsPrice />
+      <ProductDetailsPurchase />
+    </ProductDetailsRoot>
+  )}
+</QuickViewDialog>
+```
+
+`loading` and `notFound` replace those states. `error` replaces the load failure; as a function, it receives `{ message, retry }`. Replacement content renders inside the root's element, which keeps its `className`, and the error keeps `role='alert'`; a replacement loading message should have its own `role='status'`.
+
+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 image but keeps the quantity. A quantity above the new SKU's stock shows an error under the field and disables the add button. 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, display, gap and grid placement, including layered utilities such as Tailwind v4's. In `ProductDetailsOptions` and `ProductDetailsPurchase`, each control keeps a 24px bottom margin, even in a host grid. The exception is a class name the package also uses, such as `grid-cols-1` or `p-6`: the package's rule wins, even over the host's responsive variants on the same element, such as `md:grid-cols-4`. 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.
 
@@ -174,7 +205,7 @@ A part that renders nothing, such as `ProductDetailsAvailability` before a SKU i
 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.
+- `useProductDetailsOption(attribute)` returns `{ name, label, selected, missing, values, select }` for building swatches or buttons, or `null` when the product has no such attribute. Each value has `name`, `label`, `selected`, `soldOut` and `swatch` (from `getSwatch`, or `null`). `missing` is `true` once the shopper has pressed add without choosing this option, so the control can show an error; mark the control's element with `data-commerce-missing` to have add focus it. `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() {
@@ -185,6 +216,7 @@ function ColorSwatches() {
       {color.values.map((value) => (
         <button key={value.name} type='button' aria-pressed={value.selected} onClick={() => color.select(value.name)}>
           {value.label}
+          {value.soldOut && ' (sold out)'}
         </button>
       ))}
     </div>
@@ -194,35 +226,64 @@ function ColorSwatches() {
 
 Parts are flat named exports, not properties such as `ProductDetails.Title`, so each one is an ordinary module export.
 
+### Swatches
+
+Swatches are off by default: attribute values have no color or image in the catalog. Pass the provider a `getSwatch` function that returns a CSS `background` for a value, such as `'#3f6352'` or `'url(/swatches/linen.png) center / cover'`. An attribute whose values all get one renders as swatches on the product page, with the value's label as its accessible name, and catalog cards show it as dots. Any other attribute keeps its buttons.
+
+```tsx
+const colors: Record<string, string> = { forest: '#3f6352', black: '#1a1a1a', white: '#f7f7f5' };
+
+<CommerceStorefront getSwatch={({ attribute, name }) => (attribute === 'color' ? colors[name] : undefined)}>
+```
+
+### Related products
+
+`RelatedProducts` is optional and separate from `ProductDetails`. Place it where it fits, such as after the product page. It shows packaged cards for the catalog's first products, leaving out the route's `:productId` or its `productId` prop. There is no related-products API, so the products are not chosen for the current one.
+
+```tsx
+<Route
+  path='/products/:productId'
+  element={
+    <>
+      <ProductDetails />
+      <RelatedProducts className='mt-16 border-t border-commerce-line pt-12' />
+    </>
+  }
+/>
+```
+
+`title` replaces "You may also like", `limit` sets the most products, from 1 to 24 (default 4), and children replace the card, as in `CatalogProducts`. It renders nothing until the products load, when no others are left, if the request fails, or while no store is connected.
+
 ## Custom catalog layouts
 
-`Catalog` is the recommended catalog. When its layout or its cards do not fit, compose the same parts inside `CatalogRoot`. The root loads one cursor page of six products, or the built-in samples when `sampleProducts` is set and no store is connected, and shows the connection state itself. This is `<Catalog sampleProducts />` written out with its packaged card:
+`Catalog` is the recommended catalog. When its layout or its cards do not fit, compose the same parts inside `CatalogRoot`. The root loads one cursor page of six products, or `pageSize` products, or the built-in samples when `sampleProducts` is set and no store is connected, and shows the connection state itself. This is `<Catalog sampleProducts />` written out with its packaged card:
 
 ```tsx
 import {
-  CatalogHeader, CatalogPagination, CatalogProducts, CatalogRoot, CatalogSummary, ProductCardAction,
-  ProductCardDescription, ProductCardImage, ProductCardPrice, ProductCardRoot, ProductCardTitle,
+  CatalogHeader, CatalogPagination, CatalogProducts, CatalogRoot, CatalogSummary, ProductCardAction, ProductCardBadge,
+  ProductCardImage, ProductCardPrice, ProductCardRoot, ProductCardSwatches, ProductCardTitle,
 } from '@godaddy/gd-commerce-storefront';
 
 <CatalogRoot sampleProducts>
-  <CatalogHeader className='border-b border-neutral-200 pb-10 pt-4 sm:pb-14 sm:pt-8' />
-  <CatalogSummary className='border-b border-neutral-200 py-6 sm:py-8' />
-  <CatalogProducts className='grid grid-cols-1 gap-6 py-8 sm:grid-cols-2 lg:grid-cols-3 lg:gap-8 lg:py-10'>
-    <ProductCardRoot className='flex min-w-0 flex-col overflow-hidden rounded-lg border border-neutral-200'>
-      <ProductCardImage />
-      <div className='flex flex-1 flex-col p-6'>
+  <div className='flex flex-wrap items-end justify-between gap-x-4 gap-y-2 pb-6 pt-4 sm:pb-8 sm:pt-8'>
+    <CatalogHeader />
+    <CatalogSummary />
+  </div>
+  <CatalogProducts className='grid grid-cols-2 gap-x-4 gap-y-10 sm:gap-x-6 md:grid-cols-[repeat(auto-fill,minmax(240px,1fr))] lg:gap-y-12'>
+    <ProductCardRoot className='flex min-w-0 flex-col'>
+      <div className='relative'>
+        <ProductCardImage />
+        <ProductCardBadge className='pointer-events-none absolute left-3 top-3' />
+      </div>
+      <div className='flex flex-1 flex-col pt-3'>
         <ProductCardTitle />
-        <ProductCardDescription className='mt-3' />
-        <div className='mt-auto pt-6'>
-          <div className='flex flex-wrap items-end justify-between gap-4 border-t border-neutral-200 pt-5'>
-            <ProductCardPrice className='min-w-0 flex-1' />
-            <ProductCardAction className='max-w-full' />
-          </div>
-        </div>
+        <ProductCardPrice className='mt-0.5' />
+        <ProductCardSwatches className='mt-2' />
+        <ProductCardAction className='mt-auto pt-4' />
       </div>
     </ProductCardRoot>
   </CatalogProducts>
-  <CatalogPagination className='border-t border-neutral-200 pt-6' />
+  <CatalogPagination className='mt-12 border-t border-commerce-line pt-6' />
 </CatalogRoot>
 ```
 
@@ -233,12 +294,18 @@ As with product layouts, the grid, spacing and border classes come from your own
 | `CatalogHeader` | The `title` as the page's H1 and a `description`; leave it out when the host page owns the H1 |
 | `CatalogSummary` | The loading, failure or product-count status line |
 | `CatalogProducts` | One card per product. Its children are the card, rendered once for each product; without children, the packaged card |
-| `CatalogPagination` | First-page and next-page buttons; nothing for samples |
+| `CatalogEmpty` | Only when the store's catalog has no products: "No products available.", or its own children instead. While one is mounted, `CatalogProducts` leaves out its own empty message. Samples are never empty |
+| `CatalogPagination` | First-page and next-page buttons; nothing when there is one page, or for samples |
 | `ProductCardImage`, `ProductCardTitle` | The first image and the name as an H2, each linked to the product page. With a title in the card, keyboard and screen reader users get only the title link; without one, the image link takes its place once the page is interactive |
-| `ProductCardDescription`, `ProductCardPrice` | Up to three lines of description (nothing without one), and the price or price range |
-| `ProductCardAction` | Adds the product directly only when it has one SKU and no options; otherwise links to the product page to choose |
+| `ProductCardBadge` | "Sale" when some SKU's compare-at price is above that SKU's price. The catalog list has no SKU prices, so there it shows only when the lowest compare-at price is above the highest price |
+| `ProductCardPrice` | The price or price range. A single price on sale shows its compare-at price struck through; a range does not |
+| `ProductCardSwatches` | Dots for the first attribute whose values all have a [swatch](#swatches); nothing without `getSwatch` |
+| `ProductCardDescription` | Up to two lines of description; nothing without one. The packaged card leaves it out |
+| `ProductCardAction` | Adds the product directly only when it has one SKU and no options; otherwise links to the product page to choose. Its children replace the label; as a function, they receive the `action`: `add`, `choose-options` or `view-product` |
+
+`className` on `CatalogProducts` goes on the element whose direct children are the cards, so a host grid places them, and `className` on `ProductCardRoot` goes on each card, so classes such as `col-span-2` work. While products load, that element holds three placeholder cards, so they follow the host's grid. The error with its retry button and, without a `CatalogEmpty`, the empty message render just before it. Card parts take no product, SKU or price props. Inside `CatalogProducts`, `ProductCardRoot` takes no `product` prop either and throws if it gets one, so a card always shows the product it is rendered for. Samples use the same card: they show a placeholder image, no badge, description or links, and add only to the sample cart. Card and catalog parts throw if they are rendered outside their root. Packaged cards fill their grid row, with the price and action at the bottom of each card.
 
-`className` on `CatalogProducts` goes on the element whose direct children are the cards, so a host grid places them, and `className` on `ProductCardRoot` goes on each card, so classes such as `col-span-2` work. While products load, that element holds three placeholder cards, so they follow the host's grid. The error with its retry button and the empty message render just before it. Card parts take no product, SKU or price props. Inside `CatalogProducts`, `ProductCardRoot` takes no `product` prop either and throws if it gets one, so a card always shows the product it is rendered for. Samples use the same card: they show a placeholder image, no description and no links, and add only to the sample cart. Card and catalog parts throw if they are rendered outside their root. Packaged cards fill their grid row, with the price and action at the bottom of each card.
+The root keeps its page cursor in the page URL, as `after`. For a second catalog on the same page, such as a featured row above the main grid, set `urlState={false}` on it so the two do not share one cursor.
 
 For a product the host already has, such as a featured product, use `ProductCard` or `ProductCardRoot` with a `product` prop outside the catalog. `useProductCard()` returns read-only `product` (`null` for samples), `name`, `href` (`null` for samples) and `isSample` for building custom card parts. Every part accepts `className` on an outer wrapper that the package's CSS reset leaves alone, with the same limits as [product parts](#custom-product-layouts).
 
@@ -248,51 +315,59 @@ For a product the host already has, such as a featured product, use `ProductCard
 
 ```tsx
 import {
-  CartCheckout, CartCheckoutNote, CartClose, CartDescription, CartDrawerRoot, CartEmpty, CartItemImage, CartItemName,
-  CartItemOptions, CartItemPrice, CartItemQuantity, CartItemRemove, CartItemRoot, CartItems, CartNotices, CartSubtotal,
-  CartSummary, CartTitle, CommerceProvider,
+  CartCheckout, CartCheckoutNote, CartClose, CartContinueShopping, CartDescription, CartDrawerRoot, CartEmpty,
+  CartItemImage, CartItemName, CartItemOptions, CartItemPrice, CartItemQuantity, CartItemRemove, CartItemRoot, CartItems,
+  CartNotices, CartSubtotal, CartSummary, CartTitle, CommerceProvider, useCart,
 } from '@godaddy/gd-commerce-storefront';
 
+// Only the sample cart needs a description: it says nothing can be bought.
+function SampleDescription() {
+  return useCart().isSample ? <CartDescription className='mt-0.5' /> : null;
+}
+
 <CommerceProvider>
   {/* Header and routes */}
-  <CartDrawerRoot className='flex w-full max-w-lg flex-col bg-white text-neutral-900 shadow-xl'>
-    <div className='flex items-start justify-between border-b border-neutral-200 p-6'>
-      <div>
+  <CartDrawerRoot className='flex w-full max-w-md flex-col bg-white text-neutral-900 shadow-2xl'>
+    <div className='flex items-start justify-between gap-4 border-b border-commerce-line py-3 pl-6 pr-3'>
+      <div className='min-w-0 pt-2.5'>
         <CartTitle />
-        <CartDescription className='mt-1' />
+        <SampleDescription />
       </div>
       <CartClose />
     </div>
-    <div className='flex-1 overflow-y-auto p-6'>
-      <CartNotices className='mb-4' />
-      <CartItems className='divide-y divide-neutral-200'>
-        <CartItemRoot className='py-5 first:pt-0'>
-          <div className='flex gap-4'>
-            <CartItemImage />
-            <div className='min-w-0 flex-1'>
-              <CartItemName />
-              <CartItemOptions />
-              <CartItemPrice className='mt-1' />
+    <div className='flex-1 overflow-y-auto px-6'>
+      <CartNotices className='mt-6' />
+      <CartItems className='divide-y divide-commerce-line'>
+        <CartItemRoot className='flex gap-4 py-5'>
+          <CartItemImage className='shrink-0' />
+          <div className='flex min-w-0 flex-1 flex-col'>
+            <div className='flex items-start justify-between gap-4'>
+              <div className='min-w-0'>
+                <CartItemName />
+                <CartItemOptions />
+              </div>
+              <CartItemPrice className='shrink-0' />
+            </div>
+            <div className='mt-3 flex items-center justify-between gap-2'>
+              <CartItemQuantity />
+              <CartItemRemove />
             </div>
-          </div>
-          <div className='mt-4 flex items-center justify-between gap-2'>
-            <CartItemQuantity />
-            <CartItemRemove />
           </div>
         </CartItemRoot>
       </CartItems>
-      <CartEmpty className='py-16 text-center' />
+      <CartEmpty className='py-20 text-center' />
     </div>
-    <CartSummary className='border-t border-neutral-200 p-6'>
+    <CartSummary className='border-t border-commerce-line px-6 pb-6 pt-4'>
       <CartSubtotal />
-      <CartCheckoutNote className='mt-3' />
-      <CartCheckout />
+      <CartCheckoutNote className='mt-1' />
+      <CartCheckout className='mt-5' />
+      <CartContinueShopping className='mt-2' />
     </CartSummary>
   </CartDrawerRoot>
 </CommerceProvider>
 ```
 
-`className` on `CartDrawerRoot` goes on the dialog panel, which sits at the right edge at full height. The packaged width, background and column layout are the classes above; without them the panel is only as wide as its content and has no background. Add `mr-auto` to open it from the left. Keep `CartTitle` in a drawer: it names the dialog, and the dialog library logs an error without it. `CartDescription` is optional and describes the dialog when present. Render each of them once per drawer, because they use the dialog's own element IDs.
+`className` on `CartDrawerRoot` goes on the dialog panel, which sits at the right edge at full height. The packaged width, background and column layout are the classes above; without them the panel is only as wide as its content and has no background. Give the panel a background and a text color together, as `bg-white text-neutral-900` do here with `--commerce-surface` and `--commerce-text`, so the parts inside can derive their muted text and lines from it. The packaged drawer also slides in, unless the visitor prefers reduced motion. Add `mr-auto` to open it from the left. Keep `CartTitle` in a drawer: it names the dialog, and the dialog library logs an error without it. `CartDescription` is optional and describes the dialog when present. Render each of them once per drawer, because they use the dialog's own element IDs.
 
 For a cart page instead of, or as well as, the drawer, compose the same parts inside `CartRoot` on a route such as `/cart`. It shows the connection state itself, and `CartClose` renders nothing there. If the site has no drawer, use `CommerceProvider` without `CartDrawerRoot` and link to the page instead of rendering `CartButton`. Adds then open nothing, and `useCommerce().open` stays `false`. Confirm adds with the provider's `onItemAdded`, for example with a toast that links to the cart.
 
@@ -301,10 +376,10 @@ For a cart page instead of, or as well as, the drawer, compose the same parts in
 <CartRoot className='grid gap-8 lg:grid-cols-3'>
   <div className='lg:col-span-2'>
     <CartNotices className='mb-4' />
-    <CartItems className='divide-y divide-neutral-200' />
+    <CartItems className='divide-y divide-commerce-line' />
     <CartEmpty className='py-16 text-center' />
   </div>
-  <CartSummary className='rounded-lg border border-neutral-200 p-6'>
+  <CartSummary className='rounded-lg border border-commerce-line p-6'>
     <CartSubtotal />
     <CartCheckoutNote className='mt-3' />
     <CartCheckout className='mt-6' />
@@ -314,16 +389,17 @@ For a cart page instead of, or as well as, the drawer, compose the same parts in
 
 | Part | Renders |
 | --- | --- |
-| `CartTitle`, `CartDescription` | "Your cart" as an H2 and one line about it; sample wording before a store is connected |
+| `CartTitle`, `CartDescription` | "Your cart" as an H2, with the item count once there are items, and one line about it; sample wording before a store is connected |
 | `CartClose` | The drawer's close button; nothing outside the drawer |
 | `CartNotices` | A storage warning, and a cart error with a refresh button; nothing when there are neither |
 | `CartItems` | The cart lines as a list. Its child is the item, rendered once for each line; without one, the packaged item. "Loading your cart…" renders just before the list while the saved cart loads |
-| `CartItemImage`, `CartItemName`, `CartItemOptions`, `CartItemPrice` | The line's image (nothing without one), name as an H3, selected options (nothing without any) and line total |
+| `CartItemImage`, `CartItemName`, `CartItemOptions`, `CartItemPrice` | The line's image (nothing without one), name as an H3, selected options on one line, such as "Color: Blue · Size: M" (nothing without any), and line total |
 | `CartItemQuantity`, `CartItemRemove` | Decrease and increase buttons around the quantity, and the remove button |
-| `CartEmpty` | Only when the cart is empty: a message and a link to the catalog, or its own children instead |
+| `CartEmpty` | Only when the cart is empty: a bag icon, a message and a link to the catalog, or its own children instead |
 | `CartSummary` | A container that renders only when the cart has items |
-| `CartSubtotal`, `CartCheckoutNote` | The subtotal, and the note that shipping, taxes and discounts come at checkout. The note's outer element keeps the `commerce-cart-checkout-adjustments-note` class |
+| `CartSubtotal`, `CartCheckoutNote` | The subtotal, and a row saying shipping, taxes and discounts are calculated at checkout. The note's outer element keeps the `commerce-cart-checkout-adjustments-note` class |
 | `CartCheckout` | The checkout button when `checkoutSuccessPath` is set; otherwise a message that checkout is unavailable. Samples never check out |
+| `CartContinueShopping` | "Continue shopping", which closes the drawer, or links to the catalog on a cart page; nothing for an empty cart |
 
 `className` on `CartItems` goes on the list element whose direct children are the items, and `className` on `CartItemRoot` goes on each item. The list is a `role='list'` element rather than a `<ul>`, so it has no browser margin or indent for a package rule to reset. Cart and item parts take no item, quantity or price props, and they throw if they are rendered outside their root. In development builds, an item template without a `CartItemRoot` logs a warning, because the list would have no items. `CartItemImage` and `CartItemOptions` render nothing for a line without an image or options, which moves the line's other cells in a host grid. Every cart action goes through the shared provider's queue, whatever the layout, and while no store is connected the parts show the sample cart, which never reaches the store. Every part accepts `className` on an outer wrapper that the package's CSS reset leaves alone, with the same limits as [product parts](#custom-product-layouts).
 
@@ -332,6 +408,60 @@ Two hooks support custom cart markup:
 - `useCart()` works anywhere inside `CommerceProvider`. It returns read-only `items`, `itemCount`, `subtotal` (minor units, or `null` when the server has not priced the cart), `currency`, `isSample` and `loading`. Combine `itemCount` with `useCommerce().setOpen(true)` for a custom cart button.
 - `useCartItem()` returns the line inside `CartItemRoot`: `id`, `name`, `quantity`, `imageUrl`, `options`, `subtotal` and `currency`.
 
+## Replacing text
+
+The package has one rule for replacing content, so a layout never has to guess:
+
+- **A part's own text** is the part's children, such as `<CartTitle>Your bag</CartTitle>`.
+- **A state inside a loaded root**, such as an empty cart or an empty catalog, is its own part that renders only in that state: `CartEmpty` and `CatalogEmpty`. Place it anywhere in the layout.
+- **A state before the root has anything to show**, such as loading, not found or a load failure, is a root prop: `ProductDetailsRoot`'s `loading`, `notFound` and `error`. Like `<Suspense fallback>`, it replaces the root's content, because the root's children render only once its data exists. That is why `useProductDetails()` can always return a product.
+
+Parts whose wording a site often changes take replacement content as children. The part keeps its element, accessibility and rules: a replaced checkout label still waits for the cart total and still blocks a second click. As a function, the children receive the part's state, so the label can change with it. Content that is empty, such as `null`, `false`, blank text or an empty fragment, falls back to the package text. The package cannot see what a component of yours renders, so a label component that returns `null` leaves the control unlabeled. Make that choice in the children function instead, which can return `null` to keep the package text.
+
+```tsx
+<CartCheckout>{({ busy }) => (busy ? 'Redirecting…' : 'Pay securely')}</CartCheckout>
+<CartButton>{({ itemCount }) => `Bag (${itemCount})`}</CartButton>
+<ProductDetailsAddToCart>{({ soldOut }) => (soldOut ? 'Sold out' : 'Add to bag')}</ProductDetailsAddToCart>
+```
+
+| Part | Function receives |
+| --- | --- |
+| `CartTitle`, `CartDescription`, `CartContinueShopping` | `{ isSample }` |
+| `CartCheckout`, `CartItemRemove` | `{ busy }` |
+| `CartButton` | `{ itemCount }`. Replaces the icon and badge with a visible label; keep the count in it |
+| `AddToCartButton`, `ProductDetailsAddToCart` | `{ busy, soldOut }`. A `ProductDetailsAddToCart` label also replaces "Select size" and the total |
+| `ProductCardAction` | `{ action, busy, soldOut }` |
+| `ProductDetailsBackLink` | Content only |
+
+A replaced label stays the start of the control's accessible name, so voice control users can say what they see. Where the package adds the product name for screen readers, it follows as visually hidden text: `<CartItemRemove>Delete</CartItemRemove>` is named "Delete Mug". Controls without replacement text, such as "Increase quantity of Mug", keep English names.
+
+## Styling hooks
+
+Every part's outer element has a `data-commerce-part` attribute with the part's name in kebab case, such as `cart-checkout` or `product-details-option`. Roots have one too, such as `product-details-root`, including while they show the connection, loading or error state. `CartButton` and add-to-cart buttons have `cart-button` and `add-to-cart-button` on the button itself. These names, and the controls' standard state attributes (`disabled`, `aria-busy`, `aria-pressed`, `aria-invalid`, `aria-expanded`), are a stable styling API; utility classes and other markup are not.
+
+```css
+.commerce-storefront [data-commerce-part='cart-checkout'] button { border-radius: 9999px; }
+.commerce-storefront [data-commerce-part='cart-checkout'] button[aria-busy='true'] { opacity: 0.7; }
+.commerce-storefront [data-commerce-part='product-details-option'][data-commerce-attribute='color'] { display: none; }
+```
+
+`ProductDetailsOption` also has `data-commerce-attribute` with its attribute name. Controls inside a part that has more than one have `data-commerce-control`: `decrease` and `increase` in `CartItemQuantity` and `ProductDetailsQuantity`, `choice` on each option radio, and `thumbnail` in `ProductDetailsGallery`. An option the shopper skipped before pressing add has `data-commerce-missing` on its part, and its controls have `aria-invalid`. The package's utilities are unlayered and have the specificity of two classes, such as `.commerce-storefront .w-full`, or three with a state such as `:hover`. To override one, write unlayered CSS that starts with `.commerce-storefront` and a part attribute, and add the same state when the utility has one, as above. Layered host CSS, such as Tailwind v4 utilities, loses to the package's unlayered rules whatever its specificity.
+
+## Events
+
+`onEvent` on `CommerceProvider` or `CommerceStorefront` receives every cart change once the server has returned the updated cart, and every cart failure. Sample-cart changes have `isSample: true` and never reach the store.
+
+| `type` | Fields |
+| --- | --- |
+| `item-added` | `skuId` (`null` for samples), `name`, `quantity`, `isSample` |
+| `quantity-changed` | `itemId`, `quantity`, `isSample` |
+| `item-removed` | `itemId`, `isSample` |
+| `discount-applied` | `code` |
+| `checkout-started` | `cartId`; sent just before the browser leaves for checkout, so use `navigator.sendBeacon` or a keepalive request |
+| `error` | `operation` (`add`, `change-quantity`, `remove`, `discount`, `refresh` or `checkout`) and the `message` the cart shows |
+
+New event types may be added in minor releases, so ignore types you do not handle. A callback that throws or returns a rejected promise, including `onItemAdded`, is logged to the console and does not fail the cart operation. Async callbacks are not awaited, so a slow analytics call never delays the cart.
+
 ## 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.