@godaddy/gd-commerce-storefront 0.5.0 → 0.6.0

package/README.md

@@ -55,6 +55,8 @@ 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 |
 
 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.
@@ -85,9 +87,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. `--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, 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 +102,19 @@ 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 |
 | `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 and displays item count; its children replace the 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,7 +123,7 @@ 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 {
@@ -155,6 +159,23 @@ Add your own elements between parts, reorder them, or leave out display parts. `
 
 Every part is named `ProductDetails*` because it works only inside `ProductDetailsRoot`. `AddToCartButton` is the standalone button for a SKU you already have.
 
+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 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, 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.
@@ -196,7 +217,7 @@ Parts are flat named exports, not properties such as `ProductDetails.Title`, so
 
 ## 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 {
@@ -233,12 +254,15 @@ 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 |
+| `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 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 |
+| `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 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.
 
-`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).
 
@@ -332,6 +356,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` | `{ isSample }` |
+| `CartCheckout`, `CartItemRemove` | `{ busy }` |
+| `CartButton` | `{ itemCount }`. Keep the count in the label |
+| `AddToCartButton`, `ProductDetailsAddToCart` | `{ busy, soldOut }` |
+| `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 `thumbnail` in `ProductDetailsGallery`. 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.

package/dist/index.d.ts

@@ -13,7 +13,8 @@ declare class ApiError extends Error {
   readonly status: number;
   constructor(message: string, status: number, options?: ErrorOptions);
 }
-declare function money(value: number, currency: string): string;
+/** Formats minor units, such as cents, as currency. Inside the provider, prefer `useMoney`, which follows its `locale`. */
+declare function money(value: number, currency: string, locale?: string): string;
 //#endregion
 //#region src/cart-model.d.ts
 interface Money {
@@ -304,17 +305,41 @@ declare function getProductAttributes(skuGroup: SKUGroup | null | undefined): St
 /** The product's display name: its label, then its name. */
 declare function getProductName(skuGroup: SKUGroup): string;
 //#endregion
+//#region src/part.d.ts
+/** Replacement content for a part's text: content, or a function of the part's state. */
+type PartLabel<State> = ReactNode | ((state: State) => ReactNode);
+//#endregion
 //#region src/cart.d.ts
-declare function CartButton(): ReactElement;
-declare function AddToCartButton({
-  sku,
-  name,
-  quantity
-}: {
+interface CartButtonProps {
+  /** Replaces the label and count. A function receives the item count. Keep the count in the label. */
+  children?: PartLabel<{
+    itemCount: number;
+  }>;
+}
+/** Opens the cart drawer and shows the item count. */
+declare function CartButton({
+  children
+}?: CartButtonProps): ReactElement;
+/** What an add-to-cart label can depend on. */
+interface AddToCartLabelState {
+  /** The add is running. */
+  readonly busy: boolean;
+  /** Tracked stock is used up, so the button stays disabled. */
+  readonly soldOut: boolean;
+}
+interface AddToCartButtonProps {
   sku: SKU;
   name: string;
   quantity?: number;
-}): ReactElement;
+  /** Replaces the label. A function receives `busy` and `soldOut`; the button keeps its rules either way. */
+  children?: PartLabel<AddToCartLabelState>;
+}
+declare function AddToCartButton({
+  sku,
+  name,
+  quantity,
+  children
+}: AddToCartButtonProps): ReactElement;
 //#endregion
 //#region src/cart-state.d.ts
 /** One cart line, for custom cart parts. */
@@ -351,6 +376,20 @@ declare function useCart(): CartState;
 interface CartPartProps {
   className?: string;
 }
+/** Props for a cart part whose text the host can replace, with or without the sample wording. */
+interface CartTextPartProps extends CartPartProps {
+  /** Replaces the text. A function receives whether the cart is the sample cart. */
+  children?: PartLabel<{
+    isSample: boolean;
+  }>;
+}
+/** Props for a cart button whose label the host can replace. The button keeps its behavior and state. */
+interface CartActionPartProps extends CartPartProps {
+  /** Replaces the button label. A function receives whether the action is running. */
+  children?: PartLabel<{
+    busy: boolean;
+  }>;
+}
 interface CartRootProps {
   children: ReactNode;
   /** Added to the root `<section>`. */
@@ -380,12 +419,14 @@ declare function CartDrawerRoot({
 }: CartDrawerRootProps): ReactElement;
 /** "Your cart", or "Sample cart" before a store is connected, as an H2. In the drawer it names the dialog. */
 declare function CartTitle({
-  className
-}: CartPartProps): ReactElement;
+  className,
+  children
+}: CartTextPartProps): ReactElement;
 /** One line about the cart. In the drawer it describes the dialog. */
 declare function CartDescription({
-  className
-}: CartPartProps): ReactElement;
+  className,
+  children
+}: CartTextPartProps): ReactElement;
 /** The drawer's close button. Renders nothing outside the drawer. */
 declare function CartClose({
   className
@@ -440,8 +481,9 @@ declare function CartItemQuantity({
 }: CartPartProps): ReactElement;
 /** Removes the line. */
 declare function CartItemRemove({
-  className
-}: CartPartProps): ReactElement;
+  className,
+  children
+}: CartActionPartProps): ReactElement;
 interface CartEmptyProps extends CartPartProps {
   /** Replaces the default message and link. */
   children?: ReactNode;
@@ -475,8 +517,9 @@ declare function CartCheckoutNote({
  * Samples never check out. Renders nothing for an empty cart.
  */
 declare function CartCheckout({
-  className
-}: CartPartProps): ReactElement | null;
+  className,
+  children
+}: CartActionPartProps): ReactElement | null;
 /** The packaged cart drawer. Compose `CartDrawerRoot` and the cart parts for a custom drawer. */
 declare function CartDrawer(): ReactElement;
 //#endregion
@@ -491,12 +534,21 @@ interface CatalogRootProps {
   className?: string;
   /** Permit built-in examples only while the host confirms this site is unbound. */
   sampleProducts?: boolean;
+  /** Products per page, a whole number of 1 or more. Defaults to 6. Samples are always one page of six. */
+  pageSize?: number;
+  /**
+   * Keep the page cursor in the page URL, as `after`, so a reload or a shared link keeps the page. Defaults to
+   * `true`. Set `false` for every other catalog on the same page, so the catalogs do not share one cursor.
+   */
+  urlState?: boolean;
 }
 /** Loads one cursor page of products, or the built-in samples, and provides them to catalog parts. */
 declare function CatalogRoot({
   children,
   className,
-  sampleProducts
+  sampleProducts,
+  pageSize,
+  urlState
 }: CatalogRootProps): ReactElement;
 interface CatalogHeaderProps extends CatalogPartProps {
   title?: string;
@@ -518,12 +570,24 @@ interface CatalogProductsProps extends CatalogPartProps {
 }
 /**
  * The product cards. `className` goes on the element that contains the cards, such as a grid. While loading, that
- * element holds placeholder cards. The error with its retry and the empty message render just before it.
+ * element holds placeholder cards. The error with its retry and, without a `CatalogEmpty`, the empty message render just before it.
  */
 declare function CatalogProducts({
   className,
   children
 }: CatalogProductsProps): ReactElement;
+interface CatalogEmptyProps extends CatalogPartProps {
+  /** Replaces the default message. */
+  children?: ReactNode;
+}
+/**
+ * Renders only when a connected store's catalog has no products: "No products available.", or its children. While
+ * one is mounted, `CatalogProducts` leaves out its own empty message. Samples are never empty.
+ */
+declare function CatalogEmpty({
+  className,
+  children
+}: CatalogEmptyProps): ReactElement | null;
 /** First-page and next-page buttons. Renders nothing for samples, which have one page. */
 declare function CatalogPagination({
   className
@@ -537,13 +601,16 @@ interface CatalogProps {
   showHeader?: boolean;
   /** Permit built-in examples only while the host confirms this site is unbound. */
   sampleProducts?: boolean;
+  /** Products per page. Defaults to 6. */
+  pageSize?: number;
 }
 /** The packaged catalog. Compose `CatalogRoot` and the catalog parts for a custom layout. */
 declare function Catalog({
   title,
   description,
   showHeader,
-  sampleProducts
+  sampleProducts,
+  pageSize
 }: CatalogProps): ReactElement;
 //#endregion
 //#region src/commerce-provider.d.ts
@@ -553,6 +620,8 @@ interface CommerceContextValue {
   retryConnection: () => void;
   theme: StorefrontTheme;
   config: StorefrontConfig;
+  /** The BCP 47 locale that prices are formatted in, such as `en-US`. */
+  locale: string;
   cart: CartOrder | null;
   /** Whether the cart drawer is open. Always `false` when no `CartDrawer` or `CartDrawerRoot` is mounted. */
   open: boolean;
@@ -573,6 +642,11 @@ interface CommerceContextValue {
   checkout: () => Promise<boolean>;
 }
 declare function useCommerce(): CommerceContextValue;
+/**
+ * Formats minor units, such as cents, in the provider's `locale`, the way the package's own parts do. Uses the
+ * store's currency unless `currency` is given.
+ */
+declare function useMoney(): (value: number, currency?: string) => string;
 type StorefrontTheme = CSSProperties & {
   '--commerce-accent'?: string;
   '--commerce-accent-hover'?: string;
@@ -589,12 +663,54 @@ interface CommerceProviderProps {
   theme?: StorefrontTheme;
   /** Set only when your server has enabled checkout and this return route exists. */
   checkoutSuccessPath?: string;
+  /**
+   * The BCP 47 locale for formatting prices, such as `de-DE`. Defaults to `en-US`; an invalid tag falls back to it.
+   * It never selects UI text: localized text will be a separate, opt-in prop, so setting `locale` cannot change wording.
+   */
+  locale?: string;
   /**
    * Called after an item is added, live or sample. With a drawer mounted, the drawer also opens. Without one, such as
    * on a site with a cart page, use it to confirm the add.
    */
   onItemAdded?: (item: AddedCartItem) => void;
+  /** Called for every cart change and failure, such as for analytics. See `CommerceEvent`. */
+  onEvent?: (event: CommerceEvent) => void;
 }
+/** A cart operation that can fail. */
+type CommerceOperation = 'add' | 'change-quantity' | 'remove' | 'discount' | 'refresh' | 'checkout';
+/**
+ * What `onEvent` reports. Live changes are reported once the server returns the updated cart; sample changes have
+ * `isSample: true` and never reach the store. New event types may be added, so ignore types you do not handle.
+ */
+type CommerceEvent = {
+  readonly type: 'item-added';
+  /** `null` for a sample product, which is not a SKU. */
+  readonly skuId: string | null;
+  readonly name: string;
+  readonly quantity: number;
+  readonly isSample: boolean;
+} | {
+  readonly type: 'quantity-changed';
+  readonly itemId: string;
+  readonly quantity: number;
+  readonly isSample: boolean;
+} | {
+  readonly type: 'item-removed';
+  readonly itemId: string;
+  readonly isSample: boolean;
+} | {
+  readonly type: 'discount-applied';
+  readonly code: string;
+}
+/** Sent just before the browser leaves for checkout. */ | {
+  readonly type: 'checkout-started';
+  readonly cartId: string;
+}
+/** `message` is the one the cart shows. */ | {
+  readonly type: 'error';
+  readonly operation: CommerceOperation;
+  readonly message: string;
+};
 /** The item passed to `onItemAdded`. */
 interface AddedCartItem {
   readonly name: string;
@@ -608,7 +724,9 @@ declare function CommerceProvider({
   productPath,
   checkoutSuccessPath,
   theme,
-  onItemAdded
+  locale,
+  onItemAdded,
+  onEvent
 }: CommerceProviderProps): ReactElement;
 //#endregion
 //#region src/commerce-storefront.d.ts
@@ -619,6 +737,22 @@ declare function CommerceStorefront({
 }: CommerceProviderProps): react_jsx_runtime0.JSX.Element;
 //#endregion
 //#region src/product-card.d.ts
+interface ProductImageProps {
+  url?: string | null;
+  /** The alt text. Pass `''` for a decorative image, such as a thumbnail next to the product name. */
+  name: string;
+  /** Added to the image, or to its placeholder. */
+  className?: string;
+}
+/**
+ * A product image that fills its container, with a labeled placeholder when there is no URL or it fails to load.
+ * Use it in custom parts so they handle missing images like the package's own.
+ */
+declare function ProductImage({
+  url,
+  name,
+  className
+}: ProductImageProps): ReactElement;
 /** Read-only card state for custom parts rendered inside `ProductCardRoot`. */
 interface ProductCardState {
   /** `null` for a built-in sample, which is not a catalog product. */
@@ -666,13 +800,23 @@ declare function ProductCardDescription({
 declare function ProductCardPrice({
   className
 }: ProductCardPartProps): ReactElement;
+/** What a card action label can depend on. Only `add` can be busy or sold out. */
+interface ProductCardActionLabelState extends AddToCartLabelState {
+  /** `add` adds directly; `choose-options` and `view-product` link to the product page. */
+  readonly action: 'add' | 'choose-options' | 'view-product';
+}
+interface ProductCardActionProps extends ProductCardPartProps {
+  /** Replaces the button or link label. A function receives the action and its state. */
+  children?: PartLabel<ProductCardActionLabelState>;
+}
 /**
  * Adds the product directly when it has exactly one SKU and no options; otherwise links to its page to choose.
  * Samples add to the sample cart.
  */
 declare function ProductCardAction({
-  className
-}: ProductCardPartProps): ReactElement;
+  className,
+  children
+}: ProductCardActionProps): ReactElement;
 interface ProductCardProps {
   product: SKUGroup;
 }
@@ -724,19 +868,45 @@ 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. */
+  /** The product to show. Defaults to the route's `:productId` parameter. */
+  productId?: string;
+  /**
+   * Keep the selected options and SKU in the page URL, as `option.<attribute>` and `sku`, so a reload or a shared link
+   * keeps them. Defaults to `true`. Set `false` for every other root on the same page, such as a quick view, so the
+   * roots do not share one selection.
+   */
+  urlState?: boolean;
+  /** Replaces the loading message. */
+  loading?: ReactNode;
+  /** Replaces the not-found heading and link. */
+  notFound?: ReactNode;
+  /** Replaces the load failure. A function receives the failure message and a `retry` for the product request. */
+  error?: PartLabel<ProductDetailsErrorState>;
+}
+/** What a replacement for the product load failure receives. */
+interface ProductDetailsErrorState {
+  readonly message: string;
+  readonly retry: () => void;
+}
+/** Loads one product, by default the route's `:productId`, and provides state to product parts. */
 declare function ProductDetailsRoot({
-  children,
-  className
+  productId: productIdProp,
+  className,
+  ...props
 }: 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;
+interface ProductDetailsBackLinkProps extends ProductDetailsPartProps {
+  /** Replaces "← Back to shop". */
+  children?: ReactNode;
+}
+/** A link to the catalog. */
 declare function ProductDetailsBackLink({
-  className
-}: ProductDetailsPartProps): ReactElement;
+  className,
+  children
+}: ProductDetailsBackLinkProps): ReactElement;
 /** Main image with thumbnails; the selected SKU's images replace the product's when present. */
 declare function ProductDetailsGallery({
   className
@@ -784,12 +954,17 @@ declare function ProductDetailsAvailability({
 declare function ProductDetailsQuantity({
   className
 }: ProductDetailsPartProps): ReactElement | null;
+interface ProductDetailsAddToCartProps extends ProductDetailsPartProps {
+  /** Replaces the button label. A function receives `busy` and `soldOut`; the button keeps its rules either way. */
+  children?: PartLabel<AddToCartLabelState>;
+}
 /** Adds the verified SKU and quantity. While disabled, its accessible description says why. */
 declare function ProductDetailsAddToCart({
-  className
-}: ProductDetailsPartProps): ReactElement;
+  className,
+  children
+}: ProductDetailsAddToCartProps): ReactElement;
 //#endregion
 //#region src/storefront-surface.d.ts
 declare function CommerceStatus(): ReactElement | null;
 //#endregion
-export { AddToCartButton, AddToCartItemInput, type AddedCartItem, ApiError, CartAddress, CartButton, CartCheckout, CartCheckoutNote, CartClose, CartDescription, CartDiscount, CartDrawer, CartDrawerRoot, type CartDrawerRootProps, CartEmpty, type CartEmptyProps, CartItemImage, CartItemName, CartItemOptions, CartItemPrice, CartItemQuantity, CartItemRemove, CartItemRoot, type CartItemRootProps, type CartItemState, CartItems, type CartItemsProps, CartLineItem, CartLineItemDetails, CartNote, CartNotices, CartOrder, type CartPartProps, CartRoot, type CartRootProps, CartSelectedAddon, CartSelectedAddonValue, CartSelectedOption, CartShippingInfo, type CartState, CartSubtotal, CartSummary, type CartSummaryProps, CartSummaryTotals, CartTax, CartTitle, Catalog, CatalogHeader, type CatalogHeaderProps, CatalogPagination, type CatalogPartProps, CatalogProducts, type CatalogProductsProps, type CatalogProps, CatalogRoot, type CatalogRootProps, CatalogSummary, type CommerceContextValue, CommerceProvider, type CommerceProviderProps, CommerceStatus, CommerceStorefront, Connection, ConnectionEdge, DraftOrderContext, InventoryCount, LabelFilter, LineItemTotals, MediaObject, Money, OrderTotals, PageInfo, PriceRange, ProductCard, ProductCardAction, ProductCardDescription, ProductCardImage, type ProductCardPartProps, ProductCardPrice, type ProductCardProps, ProductCardRoot, type ProductCardRootProps, type ProductCardState, ProductCardTitle, 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, getProductName, getSingleMatchedSku, getSingleMatchedSkuId, money, useCart, useCartItem, useCommerce, useProductCard, useProductDetails, useProductDetailsOption };
+export { AddToCartButton, type AddToCartButtonProps, AddToCartItemInput, type AddToCartLabelState, type AddedCartItem, ApiError, type CartActionPartProps, CartAddress, CartButton, type CartButtonProps, CartCheckout, CartCheckoutNote, CartClose, CartDescription, CartDiscount, CartDrawer, CartDrawerRoot, type CartDrawerRootProps, CartEmpty, type CartEmptyProps, CartItemImage, CartItemName, CartItemOptions, CartItemPrice, CartItemQuantity, CartItemRemove, CartItemRoot, type CartItemRootProps, type CartItemState, CartItems, type CartItemsProps, CartLineItem, CartLineItemDetails, CartNote, CartNotices, CartOrder, type CartPartProps, CartRoot, type CartRootProps, CartSelectedAddon, CartSelectedAddonValue, CartSelectedOption, CartShippingInfo, type CartState, CartSubtotal, CartSummary, type CartSummaryProps, CartSummaryTotals, CartTax, type CartTextPartProps, CartTitle, Catalog, CatalogEmpty, type CatalogEmptyProps, CatalogHeader, type CatalogHeaderProps, CatalogPagination, type CatalogPartProps, CatalogProducts, type CatalogProductsProps, type CatalogProps, CatalogRoot, type CatalogRootProps, CatalogSummary, type CommerceContextValue, type CommerceEvent, type CommerceOperation, CommerceProvider, type CommerceProviderProps, CommerceStatus, CommerceStorefront, Connection, ConnectionEdge, DraftOrderContext, InventoryCount, LabelFilter, LineItemTotals, MediaObject, Money, OrderTotals, PageInfo, type PartLabel, PriceRange, ProductCard, ProductCardAction, type ProductCardActionLabelState, type ProductCardActionProps, ProductCardDescription, ProductCardImage, type ProductCardPartProps, ProductCardPrice, type ProductCardProps, ProductCardRoot, type ProductCardRootProps, type ProductCardState, ProductCardTitle, ProductDetails, ProductDetailsAddToCart, type ProductDetailsAddToCartProps, ProductDetailsAvailability, ProductDetailsBackLink, type ProductDetailsBackLinkProps, ProductDetailsDescription, type ProductDetailsErrorState, 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, ProductImage, type ProductImageProps, 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, getProductName, getSingleMatchedSku, getSingleMatchedSkuId, money, useCart, useCartItem, useCommerce, useMoney, useProductCard, useProductDetails, useProductDetailsOption };