@godaddy/gd-commerce-storefront 0.4.0 → 0.5.0

package/README.md

@@ -54,11 +54,12 @@ Use the providers your application already has; do not create another router or
 | `catalogPath` | `/shop` | Same-origin catalog route |
 | `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 |
 | `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.
 
-`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 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 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.
 
 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`.
 
@@ -78,15 +79,15 @@ A connection failure leaves the surrounding application and its state mounted. C
   }}
 >
   {/* Register /collection and /item/:productId in your router. */}
-  <Catalog title='Our collection' description='Made for everyday use.' />
+  <Catalog />
 </CommerceStorefront>
 ```
 
 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 parts](#custom-product-layouts) to change a product page's 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.
 
-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.
+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.
 
 ## Compatibility
 
@@ -99,20 +100,22 @@ 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, with `title`, `description`, and `showHeader` props |
+| `Catalog` | Six products per cursor page. 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 |
 | `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 |
-| `CartButton` | Opens the shared drawer and displays item count |
-| `AddToCartButton` | Adds a verified `sku`, `name`, and optional integer `quantity` |
+| `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 |
 | `CommerceStatus` | Connection progress/error/retry for custom layouts |
 | `useCommerce` | Cart, connection, pending/error state and serialized cart actions |
-| `CommerceProvider`, `CartDrawer` | Lower-level composition when the recommended wrapper does not fit; mount each once |
+| `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.
 
-`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.
+`Catalog` renders its title as an H1. When the host page owns its semantic heading, compose `CatalogRoot` without `CatalogHeader` (see [custom catalog layouts](#custom-catalog-layouts)) so the document still has exactly one H1. `Catalog`'s `title`, `description` and `showHeader` props still work but are deprecated: pass the copy to `CatalogHeader`, or leave `CatalogHeader` out.
 
 ## Custom product layouts
 
@@ -147,7 +150,7 @@ Add your own elements between parts, reorder them, or leave out display parts. `
 | `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 |
+| `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 |
 
 Every part is named `ProductDetails*` because it works only inside `ProductDetailsRoot`. `AddToCartButton` is the standalone button for a SKU you already have.
@@ -156,6 +159,18 @@ Parts read state from the root and take no product, SKU, price or quantity props
 
 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.
 
+Your own elements inside a root are a limit for now. The package's unlayered reset matches every element inside a root that is not a part's outer element, so layered host styles lose there:
+- **Color, font family and border** on any element.
+- **Margin, padding, font size and weight** on headings, paragraphs, lists and fieldsets.
+- **Font, color, background and border radius** on buttons, inputs and selects. Custom controls such as the swatches below are affected.
+
+Until the package scopes its reset, you can work around it:
+- Keep page headings outside the root.
+- Put colors on a part's `className`, which its children inherit.
+- Mark the affected declarations `!important`; a layered `!important` beats unlayered CSS.
+
+A part that renders nothing, such as `ProductDetailsAvailability` before a SKU is verified, leaves no grid cell, so the cells after it move up in a host grid. Wrap such parts in your own element or use named grid areas.
+
 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`.
@@ -223,10 +238,100 @@ As with product layouts, the grid, spacing and border classes come from your own
 | `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 |
 
-`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. The loading placeholder (three cards, one to three columns), the error with its retry button, and the empty message render just before that element, whatever the layout. 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.
 
 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).
 
+## Custom cart layouts
+
+`CartDrawer` is the recommended cart. `CommerceStorefront` mounts it. When its layout does not fit, use `CommerceProvider` and mount your own `CartDrawerRoot` once in its place. Development builds warn when more than one drawer is mounted, because every add would open all of them. It opens when an item is added or a `CartButton` is pressed and returns focus when it closes, like the packaged drawer. This is `CartDrawer` written out:
+
+```tsx
+import {
+  CartCheckout, CartCheckoutNote, CartClose, CartDescription, CartDrawerRoot, CartEmpty, CartItemImage, CartItemName,
+  CartItemOptions, CartItemPrice, CartItemQuantity, CartItemRemove, CartItemRoot, CartItems, CartNotices, CartSubtotal,
+  CartSummary, CartTitle, CommerceProvider,
+} from '@godaddy/gd-commerce-storefront';
+
+<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>
+        <CartTitle />
+        <CartDescription className='mt-1' />
+      </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>
+          </div>
+          <div className='mt-4 flex items-center justify-between gap-2'>
+            <CartItemQuantity />
+            <CartItemRemove />
+          </div>
+        </CartItemRoot>
+      </CartItems>
+      <CartEmpty className='py-16 text-center' />
+    </div>
+    <CartSummary className='border-t border-neutral-200 p-6'>
+      <CartSubtotal />
+      <CartCheckoutNote className='mt-3' />
+      <CartCheckout />
+    </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.
+
+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.
+
+```tsx
+<h1>Your cart</h1>
+<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' />
+    <CartEmpty className='py-16 text-center' />
+  </div>
+  <CartSummary className='rounded-lg border border-neutral-200 p-6'>
+    <CartSubtotal />
+    <CartCheckoutNote className='mt-3' />
+    <CartCheckout className='mt-6' />
+  </CartSummary>
+</CartRoot>
+```
+
+| Part | Renders |
+| --- | --- |
+| `CartTitle`, `CartDescription` | "Your cart" as an H2 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 |
+| `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 |
+| `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 |
+| `CartCheckout` | The checkout button when `checkoutSuccessPath` is set; otherwise a message that checkout is unavailable. Samples never check out |
+
+`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).
+
+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`.
+
 ## 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

@@ -315,6 +315,169 @@ declare function AddToCartButton({
   name: string;
   quantity?: number;
 }): ReactElement;
+//#endregion
+//#region src/cart-state.d.ts
+/** One cart line, for custom cart parts. */
+interface CartItemState {
+  /** Empty when the server returned a line without an ID. Such a line cannot be changed or removed. */
+  readonly id: string;
+  readonly name: string;
+  readonly quantity: number;
+  readonly imageUrl: string | null;
+  readonly options: readonly {
+    readonly attribute: string;
+    readonly values: readonly string[];
+  }[];
+  /** The line total in minor units, or `null` when the server did not price it. */
+  readonly subtotal: number | null;
+  readonly currency: string;
+}
+/** Read-only cart contents: the connected store's cart, or the sample cart while no store is connected. */
+interface CartState {
+  readonly items: readonly CartItemState[];
+  readonly itemCount: number;
+  /** The cart subtotal in minor units, or `null` when the server did not price it. */
+  readonly subtotal: number | null;
+  readonly currency: string;
+  readonly isSample: boolean;
+  /** `true` while the saved cart loads. */
+  readonly loading: boolean;
+}
+/** Read the cart from anywhere inside `CommerceProvider`, for example to build a custom cart button. */
+declare function useCart(): CartState;
+//#endregion
+//#region src/cart-parts.d.ts
+/** Props shared by every cart part. `className` is added to the part's outer element. */
+interface CartPartProps {
+  className?: string;
+}
+interface CartRootProps {
+  children: ReactNode;
+  /** Added to the root `<section>`. */
+  className?: string;
+}
+/**
+ * Provides the cart to cart parts on a page, such as a `/cart` route. While no store is connected it shows the sample
+ * cart. Use `CartDrawerRoot` for the drawer.
+ */
+declare function CartRoot({
+  children,
+  className
+}: CartRootProps): ReactElement;
+interface CartDrawerRootProps {
+  children: ReactNode;
+  /** Added to the drawer panel. The packaged drawer passes its width, background and column layout here. */
+  className?: string;
+}
+/**
+ * The cart dialog. Opens when an item is added or a `CartButton` is pressed, and returns focus when it closes.
+ * The panel sits at the right edge at full height; `mr-auto` on it moves it to the left. Mount one per provider,
+ * in place of `CartDrawer`.
+ */
+declare function CartDrawerRoot({
+  children,
+  className
+}: 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;
+/** One line about the cart. In the drawer it describes the dialog. */
+declare function CartDescription({
+  className
+}: CartPartProps): ReactElement;
+/** The drawer's close button. Renders nothing outside the drawer. */
+declare function CartClose({
+  className
+}: CartPartProps): ReactElement | null;
+/** A storage warning, and a cart error with a refresh button. Renders nothing when there are neither. */
+declare function CartNotices({
+  className
+}: CartPartProps): ReactElement | null;
+/** Read the line from inside `CartItemRoot`, for custom item parts. */
+declare function useCartItem(): CartItemState;
+interface CartItemsProps extends CartPartProps {
+  /** One item, rendered for every cart line. Defaults to the packaged item. */
+  children?: ReactNode;
+}
+/**
+ * The cart lines as a list. `className` goes on the list element whose children are the items. While the saved cart
+ * loads, a status message renders just before it.
+ */
+declare function CartItems({
+  className,
+  children
+}: CartItemsProps): ReactElement;
+interface CartItemRootProps {
+  children: ReactNode;
+  /** Added to the item's list item element. */
+  className?: string;
+}
+/** One cart line. Render it as the child of `CartItems`, which renders it once for every line. */
+declare function CartItemRoot({
+  children,
+  className
+}: CartItemRootProps): ReactElement;
+/** The line's product image. Renders nothing without one. */
+declare function CartItemImage({
+  className
+}: CartPartProps): ReactElement | null;
+/** The product name as an H3. */
+declare function CartItemName({
+  className
+}: CartPartProps): ReactElement;
+/** The selected options, one per line, such as "Color: Blue". Renders nothing without options. */
+declare function CartItemOptions({
+  className
+}: CartPartProps): ReactElement | null;
+/** The line total. */
+declare function CartItemPrice({
+  className
+}: CartPartProps): ReactElement;
+/** Decrease and increase buttons around the line's quantity. */
+declare function CartItemQuantity({
+  className
+}: CartPartProps): ReactElement;
+/** Removes the line. */
+declare function CartItemRemove({
+  className
+}: CartPartProps): ReactElement;
+interface CartEmptyProps extends CartPartProps {
+  /** Replaces the default message and link. */
+  children?: ReactNode;
+}
+/** Renders only when the cart is empty: a message and a link to the catalog, or its children. */
+declare function CartEmpty({
+  className,
+  children
+}: CartEmptyProps): ReactElement | null;
+interface CartSummaryProps extends CartPartProps {
+  children: ReactNode;
+}
+/** A container for the subtotal and checkout. Renders only when the cart has items. */
+declare function CartSummary({
+  className,
+  children
+}: CartSummaryProps): ReactElement | null;
+/** The subtotal, labeled "Sample subtotal" for samples. Renders nothing until the server prices the cart. */
+declare function CartSubtotal({
+  className
+}: CartPartProps): ReactElement | null;
+/**
+ * "Shipping, taxes, and discounts are calculated at checkout." Has the stable
+ * `commerce-cart-checkout-adjustments-note` class. Renders nothing for samples or an empty cart.
+ */
+declare function CartCheckoutNote({
+  className
+}: CartPartProps): ReactElement | null;
+/**
+ * The checkout button when `checkoutSuccessPath` is set; otherwise a message that checkout is unavailable.
+ * Samples never check out. Renders nothing for an empty cart.
+ */
+declare function CartCheckout({
+  className
+}: CartPartProps): ReactElement | null;
+/** The packaged cart drawer. Compose `CartDrawerRoot` and the cart parts for a custom drawer. */
 declare function CartDrawer(): ReactElement;
 //#endregion
 //#region src/catalog.d.ts
@@ -354,8 +517,8 @@ interface CatalogProductsProps extends CatalogPartProps {
   children?: ReactNode;
 }
 /**
- * The product cards. `className` goes on the element that contains the cards, such as a grid. The loading
- * placeholder, the error with its retry, and the empty message render just before that element.
+ * 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.
  */
 declare function CatalogProducts({
   className,
@@ -366,8 +529,11 @@ declare function CatalogPagination({
   className
 }: CatalogPartProps): ReactElement | null;
 interface CatalogProps {
+  /** @deprecated Compose `CatalogRoot` with `<CatalogHeader title='…' />` instead. */
   title?: string;
+  /** @deprecated Compose `CatalogRoot` with `<CatalogHeader description='…' />` instead. */
   description?: string;
+  /** @deprecated To render the page's own H1, compose `CatalogRoot` without `CatalogHeader` instead. */
   showHeader?: boolean;
   /** Permit built-in examples only while the host confirms this site is unbound. */
   sampleProducts?: boolean;
@@ -388,7 +554,9 @@ interface CommerceContextValue {
   theme: StorefrontTheme;
   config: StorefrontConfig;
   cart: CartOrder | null;
+  /** Whether the cart drawer is open. Always `false` when no `CartDrawer` or `CartDrawerRoot` is mounted. */
   open: boolean;
+  /** Opens or closes the cart drawer. Opening does nothing without a mounted drawer. */
   setOpen: (open: boolean) => void;
   /** Restores the initiating control after the cart drawer closes. */
   restoreFocus: () => void;
@@ -421,13 +589,26 @@ interface CommerceProviderProps {
   theme?: StorefrontTheme;
   /** Set only when your server has enabled checkout and this return route exists. */
   checkoutSuccessPath?: 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;
+}
+/** The item passed to `onItemAdded`. */
+interface AddedCartItem {
+  readonly name: string;
+  readonly quantity: number;
+  /** `true` for the sample cart, before a store is connected. */
+  readonly isSample: boolean;
 }
 declare function CommerceProvider({
   children,
   catalogPath,
   productPath,
   checkoutSuccessPath,
-  theme
+  theme,
+  onItemAdded
 }: CommerceProviderProps): ReactElement;
 //#endregion
 //#region src/commerce-storefront.d.ts
@@ -599,7 +780,7 @@ declare function ProductDetailsPurchaseStatus({
 declare function ProductDetailsAvailability({
   className
 }: ProductDetailsPartProps): ReactElement | null;
-/** Quantity for the verified SKU. Renders nothing until a SKU is verified. */
+/** Quantity for the verified SKU, with a message when it cannot be added. Renders nothing until a SKU is verified. */
 declare function ProductDetailsQuantity({
   className
 }: ProductDetailsPartProps): ReactElement | null;
@@ -611,4 +792,4 @@ declare function ProductDetailsAddToCart({
 //#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, 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, useCommerce, useProductCard, useProductDetails, useProductDetailsOption };
+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 };