@godaddy/gd-commerce-storefront 0.10.0 → 0.11.0

package/README.md

@@ -82,6 +82,7 @@ A connection failure leaves the surrounding application and its state mounted. C
     '--commerce-radius': '0.75rem',
     '--commerce-sale': '#b42318',
     '--commerce-on-sale': '#ffffff',
+    '--commerce-card-image-aspect': '1 / 1',
   }}
 >
   {/* Register /collection and /item/:productId in your router. */}
@@ -108,6 +109,8 @@ The repository example uses React Router 7. Follow each router version's own Rea
 | `CommerceStorefront` | Recommended integration: provider and one drawer |
 | `Catalog` | Six products per cursor page, 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` |
+| `useProductCard`, `useCatalog` | Card and catalog state for your own card parts, such as a category line or a product count |
+| `SampleProduct` | The type of [your own sample products](#your-own-sample-products), for a template shown before a store is connected |
 | `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 |
@@ -305,11 +308,25 @@ As with product layouts, the grid, spacing and border classes come from your own
 | `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, 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 and add only to the sample cart. They have no product page, so their title and image are not links. The packaged samples show a placeholder image and no badge or description; [your own samples](#your-own-sample-products) show their image, description and sale badge. Card images and their loading placeholders are square; set `--commerce-card-image-aspect`, such as `3 / 4`, in the `theme` or on any element around the cards to change that. 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).
+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), `sample` (the sample as you passed it, or `null` for a product), `name`, `href` (`null` for samples) and `isSample` for building custom card parts. `useCatalog()` returns the catalog's `count`, `isSample` and `status` (`loading`, `error` or `ready`) inside `CatalogRoot`, for a custom product count.
+
+Elements that are only display, such as a "Bestseller" label, a category line or a "View" link, are your own components, written with these hooks. Write such a component once and read its data where you place it, so the same label works on a card and in the cart:
+
+```tsx
+function CategoryLine() {
+  const { sample, product } = useProductCard<RoutineSample>();
+  // Samples carry your own fields; live products come from your catalog data.
+  // The type is not checked, so a sample from another catalog, such as the packaged ones, may lack your fields.
+  const category = sample ? sample.category : categoryFor(product);
+  return category ? <p className='eyebrow'>{category}</p> : null;
+}
+```
+
+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
 
@@ -408,7 +425,7 @@ For a cart page instead of, or as well as, the drawer, compose the same parts in
 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`.
+- `useCartItem()` returns the line inside `CartItemRoot`: `id`, `name`, `quantity`, `imageUrl`, `options`, `subtotal`, `currency` and `sample` (the sample as it was added, or `null` for a store line).
 
 ## Replacing text
 
@@ -531,8 +548,8 @@ A site can mount the same components before it has a connected store:
 </CommerceStorefront>
 ```
 
-`Catalog.sampleProducts` defaults to `false`. It allows six built-in sample products
-(Product 1–6, $10–$60 USD) **only** when `/api/commerce/config` reports `state: 'unbound'`.
+`Catalog.sampleProducts` defaults to `false`. `true` allows six built-in sample products
+(Product 1–6, $10–$60 USD, without images) **only** when `/api/commerce/config` reports `state: 'unbound'`.
 When a store is connected, the server reports a different state and the components show real
 products. You do not need to change props or the component tree. The prop has no effect while
 a store is connected. Real empty catalogs and errors never fall back to samples.
@@ -561,6 +578,55 @@ state for up to 60 seconds before showing the error. Once polling slows to every
 failure is already 60 seconds after the last success, so it shows the error at once. Polling
 stops when the state is `ready`; focus and explicit retry still refresh configuration.
 
+#### Your own sample products
+
+A template can show its own samples instead, with the same rule. Pass them to `sampleProducts` on
+`Catalog` or `CatalogRoot`:
+
+```tsx
+interface RoutineSample extends SampleProduct {
+  category: string;
+}
+
+const samples: RoutineSample[] = [
+  {
+    key: 'daily-cleanser',
+    name: 'Daily Cleanser',
+    price: 3200,
+    description: 'Gentle, pH-balanced foam that removes without stripping.',
+    imageUrl: '/images/cleanser.jpg',
+    category: 'Cleanse',
+  },
+];
+
+<Catalog sampleProducts={samples} />
+```
+
+Each sample needs a unique `key`, a `name` and a `price` in minor units of USD. `compareAtPrice`,
+`description` and `imageUrl` are optional. `imageUrl` is any URL the browser can load, such as a
+file in the site's own public folder; the package does not upload or check it. An image that
+fails to load shows the image placeholder on the card and no image in the cart. `CatalogRoot`
+throws, while no store is connected, for an empty list, an entry that is not an object, a
+duplicate or empty key, a packaged sample's key (`sample-1` to `sample-6`), an empty name, a
+`description` or `imageUrl` that is not a string, or a price or compare-at price that is not a
+whole number of 0 or more. Once a store is connected the samples are not shown, so development
+builds log the problem instead and the store's catalog still renders. A list written inline is
+compared by its values, so it does not rebuild the cards when it is unchanged. In a card with
+`ProductCardTitle`, a sample's image is hidden from screen readers, which read the name from the
+title.
+
+The card parts show a sample's image, description, price, and a Sale badge and struck-through
+price when `compareAtPrice` is above `price`. Samples have no product page. Fields of your own,
+such as `category`, come back unchanged from `useProductCard().sample` and, once added, from
+`useCartItem().sample`. The type you pass, as in `useProductCard<RoutineSample>()`, is not
+checked, so where other samples can appear, read your own fields as possibly missing. The sample
+cart keeps each sample as it was added, with its image, so the cart still shows it on a page
+without the catalog. While a catalog with a sample of the same key is mounted, the cart shows
+that sample's current fields, so a price or name loaded later matches the card. The cart lists
+packaged samples in catalog order and your own in the order they were added, after them. Once a
+store is connected, the same card tree shows the store's products, so build the card for both:
+your own parts read `sample` before a store is connected and `product` after.
+
 Use a server that reports connection state before you enable `sampleProducts`. Successful
 config responses without `state` still mean ready. A server that does not report `unbound`
 never shows samples. See the [server contract](docs/server-api.md) for the host's

package/dist/index.d.ts

@@ -376,9 +376,192 @@ interface AddToCartButtonProps {
 }
 declare function AddToCartButton(props: AddToCartButtonProps): ReactElement;
 //#endregion
+//#region src/commerce-provider.d.ts
+interface CommerceContextValue {
+  connection: 'loading' | 'unbound' | 'connecting' | 'ready' | 'error';
+  connectionError: string | null;
+  retryConnection: () => void;
+  theme: StorefrontTheme;
+  /** The host's swatch lookup, or `undefined` when options render as buttons. */
+  getSwatch: GetSwatch | undefined;
+  config: StorefrontConfig;
+  /** The BCP 47 locale that prices are formatted in, such as `en-US`. */
+  locale: string;
+  /** The package's text: English, with the provider's `messages` over it. */
+  messages: StorefrontMessages;
+  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;
+  pending: boolean;
+  hydrating: boolean;
+  error: string | null;
+  storageWarning: string | null;
+  announcement: string;
+  addItem: (item: AddToCartItemInput) => Promise<boolean>;
+  changeQuantity: (itemId: string, quantity: number) => Promise<boolean>;
+  removeItem: (itemId: string) => Promise<boolean>;
+  applyDiscount: (code: string) => Promise<boolean>;
+  refresh: () => Promise<boolean>;
+  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;
+/** `useMoney` for a range, such as `$20.00 – $25.00`, written the way the provider's `locale` writes ranges. */
+declare function useMoneyRange(): (min: number, max: number, currency?: string) => string;
+/**
+ * The provider's text for `key`, with `{placeholders}` filled from `values`, the way the package's own parts read
+ * it. For custom parts that should match the package's language. English outside a provider.
+ */
+declare function useMessage(): (key: StorefrontMessageKey, values?: MessageValues) => string;
+type StorefrontTheme = CSSProperties & {
+  '--commerce-accent'?: string;
+  '--commerce-accent-hover'?: string;
+  '--commerce-on-accent'?: string;
+  '--commerce-surface'?: string;
+  '--commerce-text'?: string;
+  '--commerce-radius'?: string;
+  /** Fills the Sale badge. Defaults to a red that white text reads on. */
+  '--commerce-sale'?: string;
+  /** Text on the Sale badge. Defaults to white. */
+  '--commerce-on-sale'?: string;
+  /**
+   * The aspect ratio of catalog card images and their loading placeholders, such as `3 / 4`. Defaults to `1 / 1`.
+   * Can also be set on a card or any element around it.
+   */
+  '--commerce-card-image-aspect'?: string;
+};
+/** The attribute value a host can give a swatch, such as `{ attribute: 'color', name: 'forest', label: 'Forest' }`. */
+interface SwatchValue {
+  readonly attribute: string;
+  readonly name: string;
+  readonly label: string;
+}
+/**
+ * Returns a CSS `background` for a value, such as `'#3f6352'` or `'url(/swatches/linen.png) center / cover'`, or
+ * nothing for no swatch. An attribute shows swatches only when every value has one.
+ */
+type GetSwatch = (value: SwatchValue) => string | null | undefined;
+interface CommerceProviderProps {
+  children: ReactNode;
+  catalogPath?: string;
+  productPath?: string;
+  /** Applied to storefront surfaces and the portalled cart drawer. */
+  theme?: StorefrontTheme;
+  /**
+   * Swatches for attribute values, off by default. Attributes whose values all have a swatch render as swatches on
+   * the product page, and cards show them as dots. See `GetSwatch`.
+   */
+  getSwatch?: GetSwatch;
+  /** 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; set `messages` for that.
+   */
+  locale?: string;
+  /**
+   * The package's text, such as `frFR` from `@godaddy/gd-commerce-storefront/messages/fr-FR`. Keys left out use
+   * English. Independent of `locale`, so set both for a translated store. Part `children` and props such as
+   * `CatalogHeader`'s `title` still replace the text where given.
+   */
+  messages?: Partial<StorefrontMessages>;
+  /**
+   * 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, in the provider's language. `code` is the server's failure code, such as
+ * `scope_mismatch`, when it sent one.
+ */ | {
+  readonly type: 'error';
+  readonly operation: CommerceOperation;
+  readonly message: string;
+  readonly code?: string;
+};
+/** 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,
+  getSwatch,
+  locale,
+  messages,
+  onItemAdded,
+  onEvent
+}: CommerceProviderProps): ReactElement;
+//#endregion
+//#region src/sample-cart.d.ts
+/**
+ * A product to show while no store is connected. Deliberately distinct from SKU groups, SKUs and draft orders: it
+ * is never sent to Commerce. Add any fields of your own, such as a category, and read them back from `sample` in
+ * `useProductCard()` and `useCartItem()`.
+ */
+interface SampleProduct {
+  /** Unique among the site's samples. `sample-1` to `sample-6` are the packaged samples' keys. */
+  readonly key: string;
+  readonly name: string;
+  /** In minor units of `sampleCurrency`, such as 3200 for $32.00. */
+  readonly price: number;
+  /** A higher earlier price, in minor units. The card then shows the sale badge and the struck-through price. */
+  readonly compareAtPrice?: number;
+  readonly description?: string;
+  /** Any URL the browser can load, such as a file in the site's own public folder. */
+  readonly imageUrl?: string;
+}
+//#endregion
 //#region src/cart-state.d.ts
 /** One cart line, for custom cart parts. */
-interface CartItemState {
+interface CartItemState<Sample extends SampleProduct = SampleProduct> {
   /** Empty when the server returned a line without an ID. Such a line cannot be changed or removed. */
   readonly id: string;
   readonly name: string;
@@ -391,6 +574,8 @@ interface CartItemState {
   /** The line total in minor units, or `null` when the server did not price it. */
   readonly subtotal: number | null;
   readonly currency: string;
+  /** The sample as it was added, with the site's own fields. `null` for a line in the connected store's cart. */
+  readonly sample: Sample | null;
 }
 /** Read-only cart contents: the connected store's cart, or the sample cart while no store is connected. */
 interface CartState {
@@ -473,8 +658,12 @@ declare function CartClose({
 declare function CartNotices({
   className
 }: CartPartProps): ReactElement | null;
-/** Read the line from inside `CartItemRoot`, for custom item parts. */
-declare function useCartItem(): CartItemState;
+/**
+ * Read the line from inside `CartItemRoot`, for custom item parts. Pass the type of the site's samples, such as
+ * `useCartItem<MySample>()`, to read their own fields from `sample`. The type is not checked: when the cart can hold
+ * samples from more than one catalog, read the site's own fields as possibly missing.
+ */
+declare function useCartItem<Sample extends SampleProduct = SampleProduct>(): CartItemState<Sample>;
 interface CartItemsProps extends CartPartProps {
   /** One item, rendered for every cart line. Defaults to the packaged item. */
   children?: ReactNode;
@@ -574,13 +763,29 @@ declare function CartDrawer(): ReactElement;
 interface CatalogPartProps {
   className?: string;
 }
+/** Read-only catalog state for custom catalog parts rendered inside `CatalogRoot`. */
+interface CatalogState {
+  /**
+   * Products on the current page: `0` while loading or after a first load fails. A failed refetch keeps the last page,
+   * so `status` can be `error` while `count` is above `0`.
+   */
+  readonly count: number;
+  readonly isSample: boolean;
+  /** Samples are always `ready`. */
+  readonly status: 'loading' | 'error' | 'ready';
+}
+/** Read how many products the catalog shows, and whether they are samples, for a custom summary. */
+declare function useCatalog(): CatalogState;
 interface CatalogRootProps {
   children: ReactNode;
   /** Added to the root `<section>`. */
   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. */
+  /**
+   * Products to show only while the server reports no connected store (`unbound`): `true` for the six packaged
+   * samples, or the site's own. Never shown once a store is connected. Defaults to `false`.
+   */
+  sampleProducts?: boolean | readonly SampleProduct[];
+  /** Products per page, a whole number of 1 or more. Defaults to 6. Samples are always one page. */
   pageSize?: number;
   /**
    * Keep the page cursor in the page URL, as `after`, so a reload or a shared link keeps the page. Defaults to
@@ -588,7 +793,7 @@ interface CatalogRootProps {
    */
   urlState?: boolean;
 }
-/** Loads one cursor page of products, or the built-in samples, and provides them to catalog parts. */
+/** Loads one cursor page of products, or the samples, and provides them to catalog parts. */
 declare function CatalogRoot({
   children,
   className,
@@ -649,8 +854,8 @@ interface CatalogProps {
   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;
+  /** Products to show only while no store is connected, as in `CatalogRoot`. */
+  sampleProducts?: boolean | readonly SampleProduct[];
   /** Products per page. Defaults to 6. */
   pageSize?: number;
 }
@@ -663,165 +868,6 @@ declare function Catalog({
   pageSize
 }: CatalogProps): ReactElement;
 //#endregion
-//#region src/commerce-provider.d.ts
-interface CommerceContextValue {
-  connection: 'loading' | 'unbound' | 'connecting' | 'ready' | 'error';
-  connectionError: string | null;
-  retryConnection: () => void;
-  theme: StorefrontTheme;
-  /** The host's swatch lookup, or `undefined` when options render as buttons. */
-  getSwatch: GetSwatch | undefined;
-  config: StorefrontConfig;
-  /** The BCP 47 locale that prices are formatted in, such as `en-US`. */
-  locale: string;
-  /** The package's text: English, with the provider's `messages` over it. */
-  messages: StorefrontMessages;
-  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;
-  pending: boolean;
-  hydrating: boolean;
-  error: string | null;
-  storageWarning: string | null;
-  announcement: string;
-  addItem: (item: AddToCartItemInput) => Promise<boolean>;
-  changeQuantity: (itemId: string, quantity: number) => Promise<boolean>;
-  removeItem: (itemId: string) => Promise<boolean>;
-  applyDiscount: (code: string) => Promise<boolean>;
-  refresh: () => Promise<boolean>;
-  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;
-/** `useMoney` for a range, such as `$20.00 – $25.00`, written the way the provider's `locale` writes ranges. */
-declare function useMoneyRange(): (min: number, max: number, currency?: string) => string;
-/**
- * The provider's text for `key`, with `{placeholders}` filled from `values`, the way the package's own parts read
- * it. For custom parts that should match the package's language. English outside a provider.
- */
-declare function useMessage(): (key: StorefrontMessageKey, values?: MessageValues) => string;
-type StorefrontTheme = CSSProperties & {
-  '--commerce-accent'?: string;
-  '--commerce-accent-hover'?: string;
-  '--commerce-on-accent'?: string;
-  '--commerce-surface'?: string;
-  '--commerce-text'?: string;
-  '--commerce-radius'?: string;
-  /** Fills the Sale badge. Defaults to a red that white text reads on. */
-  '--commerce-sale'?: string;
-  /** Text on the Sale badge. Defaults to white. */
-  '--commerce-on-sale'?: string;
-};
-/** The attribute value a host can give a swatch, such as `{ attribute: 'color', name: 'forest', label: 'Forest' }`. */
-interface SwatchValue {
-  readonly attribute: string;
-  readonly name: string;
-  readonly label: string;
-}
-/**
- * Returns a CSS `background` for a value, such as `'#3f6352'` or `'url(/swatches/linen.png) center / cover'`, or
- * nothing for no swatch. An attribute shows swatches only when every value has one.
- */
-type GetSwatch = (value: SwatchValue) => string | null | undefined;
-interface CommerceProviderProps {
-  children: ReactNode;
-  catalogPath?: string;
-  productPath?: string;
-  /** Applied to storefront surfaces and the portalled cart drawer. */
-  theme?: StorefrontTheme;
-  /**
-   * Swatches for attribute values, off by default. Attributes whose values all have a swatch render as swatches on
-   * the product page, and cards show them as dots. See `GetSwatch`.
-   */
-  getSwatch?: GetSwatch;
-  /** 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; set `messages` for that.
-   */
-  locale?: string;
-  /**
-   * The package's text, such as `frFR` from `@godaddy/gd-commerce-storefront/messages/fr-FR`. Keys left out use
-   * English. Independent of `locale`, so set both for a translated store. Part `children` and props such as
-   * `CatalogHeader`'s `title` still replace the text where given.
-   */
-  messages?: Partial<StorefrontMessages>;
-  /**
-   * 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, in the provider's language. `code` is the server's failure code, such as
- * `scope_mismatch`, when it sent one.
- */ | {
-  readonly type: 'error';
-  readonly operation: CommerceOperation;
-  readonly message: string;
-  readonly code?: string;
-};
-/** 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,
-  getSwatch,
-  locale,
-  messages,
-  onItemAdded,
-  onEvent
-}: CommerceProviderProps): ReactElement;
-//#endregion
 //#region src/commerce-storefront.d.ts
 /** Mount once inside the application's Router and QueryClientProvider. */
 declare function CommerceStorefront({
@@ -847,9 +893,11 @@ declare function ProductImage({
   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. */
+interface ProductCardState<Sample extends SampleProduct = SampleProduct> {
+  /** `null` for a sample, which is not a catalog product. */
   readonly product: SKUGroup | null;
+  /** The sample as the site passed it to `sampleProducts`, with its own fields. `null` for a catalog product. */
+  readonly sample: Sample | null;
   readonly name: string;
   /** The product page, or `null` for a sample, which has none. */
   readonly href: string | null;
@@ -859,8 +907,12 @@ interface ProductCardState {
 interface ProductCardPartProps {
   className?: string;
 }
-/** Read the card's product, name, and link from inside `ProductCardRoot`. */
-declare function useProductCard(): ProductCardState;
+/**
+ * Read the card's product or sample, name, and link from inside `ProductCardRoot`. Pass the type of the site's
+ * samples, such as `useProductCard<MySample>()`, to read their own fields from `sample`. The type is not checked:
+ * on a page that also shows the packaged samples, read the site's own fields as possibly missing.
+ */
+declare function useProductCard<Sample extends SampleProduct = SampleProduct>(): ProductCardState<Sample>;
 interface ProductCardRootProps {
   children: ReactNode;
   /** The catalog product to show. Leave it out inside `CatalogProducts`, which supplies each product. */
@@ -875,8 +927,9 @@ declare function ProductCardRoot({
   className
 }: ProductCardRootProps): ReactElement;
 /**
- * The product's first image, linked to its page. Samples show a placeholder. With a `ProductCardTitle` in the card,
- * the title is the one link keyboard and screen reader users get; without one, the image link is.
+ * The product's first image, linked to its page. A sample shows its `imageUrl`, unlinked, or the packaged samples'
+ * placeholder. With a `ProductCardTitle` in the card, the title is the one link keyboard and screen reader users get,
+ * and a sample's image is hidden from screen readers so its name is not read twice; without one, the image is exposed.
  */
 declare function ProductCardImage({
   className
@@ -885,13 +938,14 @@ declare function ProductCardImage({
 declare function ProductCardTitle({
   className
 }: ProductCardPartProps): ReactElement;
-/** Up to three lines of the product description. Renders nothing without one. */
+/** Up to two lines of the product or sample description. Renders nothing without one. */
 declare function ProductCardDescription({
   className
 }: ProductCardPartProps): ReactElement | null;
 /**
  * "Sale" when some SKU's compare-at price is above that SKU's price. Without SKU prices, as in the catalog list, only
- * when the lowest compare-at price is above the highest price. Renders nothing otherwise, or for samples.
+ * when the lowest compare-at price is above the highest price. For a sample, when its `compareAtPrice` is above its
+ * price. Renders nothing otherwise.
  */
 declare function ProductCardBadge({
   className
@@ -1133,4 +1187,4 @@ declare function RelatedProducts({
 //#region src/storefront-surface.d.ts
 declare function CommerceStatus(): ReactElement | null;
 //#endregion
-export { AddToCartButton, type AddToCartButtonProps, AddToCartItemInput, type AddToCartLabelState, type AddedCartItem, ApiError, type CartActionPartProps, CartAddress, CartButton, type CartButtonProps, CartCheckout, CartCheckoutNote, CartClose, CartContinueShopping, 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 CommerceErrorCode, type CommerceEvent, type CommerceOperation, CommerceProvider, type CommerceProviderProps, CommerceStatus, CommerceStorefront, Connection, ConnectionEdge, DraftOrderContext, type GetSwatch, InventoryCount, LabelFilter, LineItemTotals, MediaObject, type MessageValues, Money, OrderTotals, PageInfo, type PartLabel, PriceRange, ProductCard, ProductCardAction, type ProductCardActionLabelState, type ProductCardActionProps, ProductCardBadge, ProductCardDescription, ProductCardImage, type ProductCardPartProps, ProductCardPrice, type ProductCardProps, ProductCardRoot, type ProductCardRootProps, type ProductCardState, ProductCardSwatches, ProductCardTitle, ProductDetails, ProductDetailsAddToCart, type ProductDetailsAddToCartProps, ProductDetailsAvailability, ProductDetailsBackLink, type ProductDetailsBackLinkProps, ProductDetailsBadge, 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, RelatedProducts, type RelatedProductsProps, SKU, SKUAttributeValue, SKUGroup, SKUGroupAttribute, SKUGroupAttributeValue, SKUGroupSKU, SKUPrice, SkuGroupResult, SkuGroupVariables, SkuGroupsResult, SkuGroupsVariables, SkuResult, SkuVariables, type StorefrontConfig, type StorefrontMessage, type StorefrontMessageKey, type StorefrontMessages, StorefrontProductAttribute, StorefrontProductAttributeValue, type StorefrontTheme, StringInFilter, type SwatchValue, addToCart, enUS, formatMessage, getAvailableInventoryQuantity, getCartSummaryTotals, getImageUrls, getLabeledSkuOptions, getPrimaryImageUrl, getProductAttributes, getProductName, getSingleMatchedSku, getSingleMatchedSkuId, getSkuAttributeValueNames, getStartingCompareAt, inSentence, isOnSale, isProductOnSale, money, moneyRange, useCart, useCartItem, useCommerce, useMessage, useMoney, useMoneyRange, useProductCard, useProductDetails, useProductDetailsOption };
+export { AddToCartButton, type AddToCartButtonProps, AddToCartItemInput, type AddToCartLabelState, type AddedCartItem, ApiError, type CartActionPartProps, CartAddress, CartButton, type CartButtonProps, CartCheckout, CartCheckoutNote, CartClose, CartContinueShopping, 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, type CatalogState, CatalogSummary, type CommerceContextValue, type CommerceErrorCode, type CommerceEvent, type CommerceOperation, CommerceProvider, type CommerceProviderProps, CommerceStatus, CommerceStorefront, Connection, ConnectionEdge, DraftOrderContext, type GetSwatch, InventoryCount, LabelFilter, LineItemTotals, MediaObject, type MessageValues, Money, OrderTotals, PageInfo, type PartLabel, PriceRange, ProductCard, ProductCardAction, type ProductCardActionLabelState, type ProductCardActionProps, ProductCardBadge, ProductCardDescription, ProductCardImage, type ProductCardPartProps, ProductCardPrice, type ProductCardProps, ProductCardRoot, type ProductCardRootProps, type ProductCardState, ProductCardSwatches, ProductCardTitle, ProductDetails, ProductDetailsAddToCart, type ProductDetailsAddToCartProps, ProductDetailsAvailability, ProductDetailsBackLink, type ProductDetailsBackLinkProps, ProductDetailsBadge, 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, RelatedProducts, type RelatedProductsProps, SKU, SKUAttributeValue, SKUGroup, SKUGroupAttribute, SKUGroupAttributeValue, SKUGroupSKU, SKUPrice, type SampleProduct, SkuGroupResult, SkuGroupVariables, SkuGroupsResult, SkuGroupsVariables, SkuResult, SkuVariables, type StorefrontConfig, type StorefrontMessage, type StorefrontMessageKey, type StorefrontMessages, StorefrontProductAttribute, StorefrontProductAttributeValue, type StorefrontTheme, StringInFilter, type SwatchValue, addToCart, enUS, formatMessage, getAvailableInventoryQuantity, getCartSummaryTotals, getImageUrls, getLabeledSkuOptions, getPrimaryImageUrl, getProductAttributes, getProductName, getSingleMatchedSku, getSingleMatchedSkuId, getSkuAttributeValueNames, getStartingCompareAt, inSentence, isOnSale, isProductOnSale, money, moneyRange, useCart, useCartItem, useCatalog, useCommerce, useMessage, useMoney, useMoneyRange, useProductCard, useProductDetails, useProductDetailsOption };

package/dist/index.js

@@ -348,16 +348,50 @@ function getCartSummaryTotals(order, fallbackCurrency = "USD") {
 
 //#endregion
 //#region src/sample-cart.tsx
-const sampleProducts = Array.from({ length: 6 }, (_, index) => ({
+/** The six packaged samples, "Product 1" to "Product 6", without images. */
+const builtInSamples = Array.from({ length: 6 }, (_, index) => ({
 	key: `sample-${index + 1}`,
-	number: index + 1,
+	name: `Product ${index + 1}`,
 	price: (index + 1) * 1e3
 }));
+const builtInNumbers = new Map(builtInSamples.map((sample, index) => [sample.key, index + 1]));
+const builtInNumber = (sample) => builtInNumbers.get(sample.key);
+const isBuiltInSample = (sample) => builtInNumber(sample) !== void 0;
 /** Sample prices are examples, in this currency whatever the store's. */
 const sampleCurrency = "USD";
-/** A sample's name, such as "Product 1". The card and the cart both name samples with this. */
-const sampleName = (text, sample) => text("sampleProductName", { number: sample.number });
-const noQuantities = {};
+/** A sample's name. Packaged samples are named in the provider's language, such as "Product 1". */
+const sampleName = (text, sample) => {
+	const number = builtInNumber(sample);
+	return number === void 0 ? sample.name : text("sampleProductName", { number });
+};
+const validPrice = (price) => Number.isSafeInteger(price) && price >= 0;
+/** The first reason host samples could not be shown or added consistently, or `null` when they can. */
+function sampleProblem(samples) {
+	if (!samples.length) return "CatalogRoot sampleProducts needs at least one product, or `true`.";
+	const keys = /* @__PURE__ */ new Set();
+	for (const [index, sample] of samples.entries()) {
+		if (typeof sample !== "object" || sample === null) return `CatalogRoot sampleProducts: entry ${index} is ${String(sample)}, not a sample.`;
+		if (typeof sample.key !== "string" || !sample.key || keys.has(sample.key)) return `CatalogRoot sampleProducts need unique, non-empty string keys, not "${String(sample.key)}".`;
+		if (builtInNumbers.has(sample.key)) return `CatalogRoot sampleProducts: "${sample.key}" is a packaged sample's key. Use another key.`;
+		keys.add(sample.key);
+		if (typeof sample.name !== "string" || !sample.name.trim()) return `CatalogRoot sampleProducts: "${sample.key}" needs a non-empty name.`;
+		for (const field of ["description", "imageUrl"]) if (sample[field] !== void 0 && typeof sample[field] !== "string") return `CatalogRoot sampleProducts: "${sample.key}" has a ${field} that is not a string.`;
+		for (const field of ["price", "compareAtPrice"]) {
+			const value = sample[field];
+			if ((field === "price" || value !== void 0) && !validPrice(value)) return `CatalogRoot sampleProducts: "${sample.key}" has an invalid ${field}, ${String(value)}. A price must be a whole number of minor units, 0 or more.`;
+		}
+	}
+	return null;
+}
+const sameSample = (a, b) => {
+	if (a === b) return true;
+	if (typeof a !== "object" || !a || typeof b !== "object" || !b) return false;
+	const fields = Object.keys(a);
+	return fields.length === Object.keys(b).length && fields.every((field) => Object.is(a[field], b[field]));
+};
+/** Whether two sample lists have the same samples with the same field values, so an inline list can be reused. */
+const sameSamples = (a, b) => a === b || a.length === b.length && a.every((sample, index) => sameSample(sample, b[index]));
+const noLines = [];
 const SampleCartContext = createContext(null);
 function useSampleCart() {
 	const value = useContext(SampleCartContext);
@@ -371,37 +405,73 @@ function SampleCartProvider({ enabled, messages, onAdd, announce, emit, children
 	active.current = session;
 	const [state, setState] = useState({
 		session,
-		quantities: {}
+		lines: noLines
 	});
 	useEffect(() => {
 		active.current = session;
 		setState({
 			session,
-			quantities: {}
+			lines: noLines
 		});
 		return () => {
 			active.current = null;
 		};
 	}, [session]);
-	const quantities = state.session === session && enabled ? state.quantities : noQuantities;
-	const items = useMemo(() => sampleProducts.flatMap((product) => quantities[product.key] ? [{
-		...product,
-		name: sampleName(text, product),
-		quantity: quantities[product.key]
-	}] : []), [quantities, text]);
-	function update(key, quantity) {
-		if (!enabled || active.current !== session || !sampleProducts.some((product) => product.key === key)) return false;
+	const lines = state.session === session && enabled ? state.lines : noLines;
+	const items = useMemo(() => [...lines].sort((a, b) => (builtInNumber(a.sample) ?? Number.POSITIVE_INFINITY) - (builtInNumber(b.sample) ?? Number.POSITIVE_INFINITY)).map(({ sample, quantity }) => ({
+		key: sample.key,
+		name: sampleName(text, sample),
+		price: sample.price,
+		quantity,
+		sample
+	})), [lines, text]);
+	const refresh = useCallback((samples) => {
+		const byKey = new Map(samples.map((sample) => [sample.key, sample]));
+		setState((previous) => {
+			if (previous.session !== session) return previous;
+			let changed = false;
+			const next = previous.lines.map((line) => {
+				const current = byKey.get(line.sample.key);
+				if (!current || current === line.sample) return line;
+				changed = true;
+				return {
+					...line,
+					sample: current
+				};
+			});
+			return changed ? {
+				session,
+				lines: next
+			} : previous;
+		});
+	}, [session]);
+	function update(key, quantity, added) {
+		if (!enabled || active.current !== session) return false;
+		if (!added && !lines.some((line) => line.sample.key === key)) return false;
 		if (quantity !== void 0 && (!Number.isSafeInteger(quantity) || quantity < 0 || quantity > 999)) return false;
 		setState((previous) => {
-			const current = previous.session === session ? previous.quantities : {};
-			const next = quantity ?? (current[key] ?? 0) + 1;
+			const current = previous.session === session ? previous.lines : noLines;
+			const line = current.find((candidate) => candidate.sample.key === key);
+			const next = quantity ?? (line?.quantity ?? 0) + 1;
 			if (next > 999) return previous;
+			const kept = current.filter((candidate) => candidate !== line);
+			if (next === 0) return {
+				session,
+				lines: kept
+			};
+			if (!line && added) return {
+				session,
+				lines: [...current, {
+					sample: added,
+					quantity: next
+				}]
+			};
 			return {
 				session,
-				quantities: {
-					...current,
-					[key]: next
-				}
+				lines: current.map((candidate) => candidate === line ? {
+					...candidate,
+					quantity: next
+				} : candidate)
 			};
 		});
 		return true;
@@ -409,10 +479,10 @@ function SampleCartProvider({ enabled, messages, onAdd, announce, emit, children
 	return /* @__PURE__ */ jsx(SampleCartContext.Provider, {
 		value: {
 			items,
-			add: (key) => {
-				const product = sampleProducts.find((product$1) => product$1.key === key);
-				if (!product || !update(key)) return false;
-				onAdd(sampleName(text, product));
+			refresh,
+			add: (sample) => {
+				if (!update(sample.key, void 0, sample)) return false;
+				onAdd(sampleName(text, sample));
 				return true;
 			},
 			changeQuantity: async (key, quantity) => {
@@ -977,20 +1047,21 @@ function useCart() {
 	const { cart, config, connection, hydrating } = useCommerce();
 	const sample = useSampleCart();
 	const isSample = connection === "unbound";
-	const sampleItems$1 = sample.items;
+	const sampleItems = sample.items;
 	return useMemo(() => {
 		if (isSample) return {
-			items: sampleItems$1.map((item) => ({
+			items: sampleItems.map((item) => ({
 				id: item.key,
 				name: item.name,
 				quantity: item.quantity,
-				imageUrl: null,
+				imageUrl: item.sample.imageUrl || null,
 				options: [],
 				subtotal: item.price * item.quantity,
-				currency: sampleCurrency
+				currency: sampleCurrency,
+				sample: item.sample
 			})),
-			itemCount: sampleItems$1.reduce((total, item) => total + item.quantity, 0),
-			subtotal: sampleItems$1.reduce((sum, item) => sum + item.price * item.quantity, 0),
+			itemCount: sampleItems.reduce((total, item) => total + item.quantity, 0),
+			subtotal: sampleItems.reduce((sum, item) => sum + item.price * item.quantity, 0),
 			currency: sampleCurrency,
 			isSample,
 			loading: false
@@ -1009,7 +1080,8 @@ function useCart() {
 					values: option.values ?? []
 				})),
 				subtotal: typeof item.totals?.subTotal?.value === "number" ? item.totals.subTotal.value : null,
-				currency: item.totals?.subTotal?.currencyCode ?? currency
+				currency: item.totals?.subTotal?.currencyCode ?? currency,
+				sample: null
 			})),
 			itemCount: lines.reduce((total, item) => total + (item.quantity ?? 0), 0),
 			subtotal: typeof subtotal === "number" ? subtotal : null,
@@ -1022,7 +1094,7 @@ function useCart() {
 		config.currencyCode,
 		hydrating,
 		isSample,
-		sampleItems$1
+		sampleItems
 	]);
 }
 
@@ -1574,7 +1646,11 @@ function useCartItemInternal(part) {
 	if (!item) throw new Error(`${part} must be rendered inside <CartItemRoot>.`);
 	return item;
 }
-/** Read the line from inside `CartItemRoot`, for custom item parts. */
+/**
+* Read the line from inside `CartItemRoot`, for custom item parts. Pass the type of the site's samples, such as
+* `useCartItem<MySample>()`, to read their own fields from `sample`. The type is not checked: when the cart can hold
+* samples from more than one catalog, read the site's own fields as possibly missing.
+*/
 function useCartItem() {
 	return useCartItemInternal("useCartItem");
 }
@@ -1630,13 +1706,15 @@ function CartItemRoot({ children, className }) {
 /** The line's product image. Renders nothing without one. */
 function CartItemImage({ className }) {
 	const { imageUrl } = useCartItemInternal("CartItemImage");
-	if (!imageUrl) return null;
+	const [failedUrl, setFailedUrl] = useState(null);
+	if (!imageUrl || imageUrl === failedUrl) return null;
 	return /* @__PURE__ */ jsx("div", {
 		...partProps("cart-item-image", className),
 		children: /* @__PURE__ */ jsx("img", {
 			src: imageUrl,
 			alt: "",
-			className: "h-20 w-20 bg-commerce-tint object-cover"
+			className: "h-20 w-20 bg-commerce-tint object-cover",
+			onError: () => setFailedUrl(imageUrl)
 		})
 	});
 }
@@ -1973,7 +2051,7 @@ function ProductImage({ url, name, className = "" }) {
 }
 /** Set by `CatalogProducts` for each entry it renders, so the card template needs no product prop. */
 const CatalogItemContext = createContext(null);
-const titleLink = "title-link";
+const titleLink = "title";
 function cardValue(item, productPath, links, sampleNameText) {
 	if (item.source === "sample") return {
 		...links,
@@ -1999,16 +2077,24 @@ function useProductCardInternal(part) {
 	if (!context) throw new Error(`${part} must be rendered inside <ProductCardRoot>.`);
 	return context;
 }
-/** Read the card's product, name, and link from inside `ProductCardRoot`. */
+/**
+* Read the card's product or sample, name, and link from inside `ProductCardRoot`. Pass the type of the site's
+* samples, such as `useProductCard<MySample>()`, to read their own fields from `sample`. The type is not checked:
+* on a page that also shows the packaged samples, read the site's own fields as possibly missing.
+*/
 function useProductCard() {
-	const { product, name, href, isSample } = useProductCardInternal("useProductCard");
+	const card = useProductCardInternal("useProductCard");
+	const { product, name, href, isSample } = card;
+	const sample = card.source === "sample" ? card.sample : null;
 	return useMemo(() => ({
 		product,
+		sample,
 		name,
 		href,
 		isSample
 	}), [
 		product,
+		sample,
 		name,
 		href,
 		isSample
@@ -2057,8 +2143,9 @@ function ProductCardRoot({ children, product, className }) {
 	return catalogItem ? card : /* @__PURE__ */ jsx(StorefrontSurface, { children: card });
 }
 /**
-* The product's first image, linked to its page. Samples show a placeholder. With a `ProductCardTitle` in the card,
-* the title is the one link keyboard and screen reader users get; without one, the image link is.
+* The product's first image, linked to its page. A sample shows its `imageUrl`, unlinked, or the packaged samples'
+* placeholder. With a `ProductCardTitle` in the card, the title is the one link keyboard and screen reader users get,
+* and a sample's image is hidden from screen readers so its name is not read twice; without one, the image is exposed.
 */
 function ProductCardImage({ className }) {
 	const card = useProductCardInternal("ProductCardImage");
@@ -2068,23 +2155,30 @@ function ProductCardImage({ className }) {
 			to: card.href,
 			tabIndex: card.imageLinked ? void 0 : -1,
 			"aria-hidden": card.imageLinked ? void 0 : "true",
-			className: "block aspect-square overflow-hidden bg-commerce-tint focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-current",
+			className: "block aspect-(--commerce-card-image-aspect,1/1) overflow-hidden bg-commerce-tint focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-current",
 			children: /* @__PURE__ */ jsx(ProductImage, {
 				url: getPrimaryImageUrl(card.product),
 				name: card.name,
 				className: "motion-safe:transition-transform motion-safe:duration-500 motion-safe:ease-out motion-safe:group-hover:scale-[1.03]"
 			})
-		}) : /* @__PURE__ */ jsx("div", {
+		}) : isBuiltInSample(card.sample) ? /* @__PURE__ */ jsx("div", {
 			"aria-hidden": "true",
-			className: "flex aspect-square items-center justify-center bg-commerce-tint",
+			className: "flex aspect-(--commerce-card-image-aspect,1/1) items-center justify-center bg-commerce-tint",
 			children: /* @__PURE__ */ jsx("div", { className: "h-16 w-16 rounded-full border border-commerce-line" })
+		}) : /* @__PURE__ */ jsx("div", {
+			"aria-hidden": card.imageLinked ? void 0 : "true",
+			className: "aspect-(--commerce-card-image-aspect,1/1) overflow-hidden bg-commerce-tint",
+			children: /* @__PURE__ */ jsx(ProductImage, {
+				url: card.sample.imageUrl,
+				name: card.name
+			})
 		})
 	});
 }
 /** The product name as an H2, linked to its page. */
 function ProductCardTitle({ className }) {
 	const { name, href, register } = useProductCardInternal("ProductCardTitle");
-	useEffect(() => href ? register(titleLink) : void 0, [href, register]);
+	useEffect(() => register(titleLink), [register]);
 	return /* @__PURE__ */ jsx("div", {
 		...partProps("product-card-title", className),
 		children: /* @__PURE__ */ jsx("h2", {
@@ -2097,15 +2191,16 @@ function ProductCardTitle({ className }) {
 		})
 	});
 }
-/** Up to three lines of the product description. Renders nothing without one. */
+/** Up to two lines of the product or sample description. Renders nothing without one. */
 function ProductCardDescription({ className }) {
-	const { product } = useProductCardInternal("ProductCardDescription");
-	if (!product?.description) return null;
+	const card = useProductCardInternal("ProductCardDescription");
+	const description = card.source === "sample" ? card.sample.description : card.product.description;
+	if (!description) return null;
 	return /* @__PURE__ */ jsx("div", {
 		...partProps("product-card-description", className),
 		children: /* @__PURE__ */ jsx("p", {
 			className: "line-clamp-2 text-sm leading-6 text-commerce-muted",
-			children: product.description
+			children: description
 		})
 	});
 }
@@ -2117,12 +2212,13 @@ const formatRange = (range, money$1, moneyRange$1) => {
 };
 /**
 * "Sale" when some SKU's compare-at price is above that SKU's price. Without SKU prices, as in the catalog list, only
-* when the lowest compare-at price is above the highest price. Renders nothing otherwise, or for samples.
+* when the lowest compare-at price is above the highest price. For a sample, when its `compareAtPrice` is above its
+* price. Renders nothing otherwise.
 */
 function ProductCardBadge({ className }) {
-	const { product } = useProductCardInternal("ProductCardBadge");
+	const card = useProductCardInternal("ProductCardBadge");
 	const text = useMessage();
-	if (!isProductOnSale(product)) return null;
+	if (card.source === "sample" ? sampleCompareAt(card.sample) === null : !isProductOnSale(card.product)) return null;
 	return /* @__PURE__ */ jsx("div", {
 		...partProps("product-card-badge", className),
 		children: /* @__PURE__ */ jsx("span", {
@@ -2131,6 +2227,7 @@ function ProductCardBadge({ className }) {
 		})
 	});
 }
+const sampleCompareAt = (sample) => sample.compareAtPrice !== void 0 && sample.compareAtPrice > sample.price ? sample.compareAtPrice : null;
 /** The product's price, or its price range when variants differ. A single price on sale shows its compare-at price. */
 function ProductCardPrice({ className }) {
 	const card = useProductCardInternal("ProductCardPrice");
@@ -2139,8 +2236,10 @@ function ProductCardPrice({ className }) {
 	const message = useMessage();
 	const text = card.source === "sample" ? money$1(card.sample.price, sampleCurrency) : formatRange(card.product.priceRange, money$1, moneyRange$1) ?? message("priceUnavailable");
 	const range = card.source === "live" ? card.product.priceRange : null;
-	const starting = card.source === "live" && range?.min === range?.max ? getStartingCompareAt(card.product) : null;
-	const compareAt = starting === null ? null : money$1(starting);
+	let starting = null;
+	if (card.source === "sample") starting = sampleCompareAt(card.sample);
+	else if (range?.min === range?.max) starting = getStartingCompareAt(card.product);
+	const compareAt = starting === null ? null : money$1(starting, card.source === "sample" ? sampleCurrency : void 0);
 	return /* @__PURE__ */ jsx("div", {
 		...partProps("product-card-price", className),
 		children: /* @__PURE__ */ jsxs("p", {
@@ -2263,12 +2362,12 @@ function SampleAction({ sample, label }) {
 		type: "button",
 		className: `${secondaryButtonClass} w-full`,
 		"aria-label": text("addSampleToCart", { name }),
-		onClick: () => add(sample.key),
+		onClick: () => add(sample),
 		children: text("addToCart")
 	}) : /* @__PURE__ */ jsxs("button", {
 		type: "button",
 		className: `${secondaryButtonClass} w-full`,
-		onClick: () => add(sample.key),
+		onClick: () => add(sample),
 		children: [custom, /* @__PURE__ */ jsxs("span", {
 			className: "sr-only",
 			children: [" ", text("sampleItemName", { name })]
@@ -2319,14 +2418,39 @@ function useRootParams(urlState) {
 //#region src/catalog.tsx
 const CatalogContext = createContext(null);
 const CatalogEmptyContext = createContext(null);
-const sampleCatalog = { source: "sample" };
+const builtInCatalog = {
+	source: "sample",
+	samples: builtInSamples
+};
 function useCatalogInternal(part) {
 	const context = useContext(CatalogContext);
 	if (!context) throw new Error(`${part} must be rendered inside <CatalogRoot>.`);
 	return context;
 }
-/** Loads one cursor page of products, or the built-in samples, and provides them to catalog parts. */
-function CatalogRoot({ children, className, sampleProducts: sampleProducts$1 = false, pageSize = 6, urlState = true }) {
+/** Read how many products the catalog shows, and whether they are samples, for a custom summary. */
+function useCatalog() {
+	const catalog = useCatalogInternal("useCatalog");
+	let count;
+	let status = "ready";
+	if (catalog.source === "sample") count = catalog.samples.length;
+	else {
+		count = catalog.nodes.length;
+		if (catalog.products.isPending) status = "loading";
+		else if (catalog.products.isError) status = "error";
+	}
+	const isSample = catalog.source === "sample";
+	return useMemo(() => ({
+		count,
+		isSample,
+		status
+	}), [
+		count,
+		isSample,
+		status
+	]);
+}
+/** Loads one cursor page of products, or the samples, and provides them to catalog parts. */
+function CatalogRoot({ children, className, sampleProducts = false, pageSize = 6, urlState = true }) {
 	const { connection } = useCommerce();
 	const [custom, setCustom] = useState(false);
 	const { register, has } = usePartRegistry(useCallback((registered) => setCustom(registered("empty")), []));
@@ -2338,6 +2462,25 @@ function CatalogRoot({ children, className, sampleProducts: sampleProducts$1 = f
 		custom
 	}), [register, custom]);
 	if (!Number.isSafeInteger(pageSize) || pageSize < 1) throw new Error(`CatalogRoot pageSize must be a whole number of 1 or more, not ${pageSize}.`);
+	const hostSamples = useStableSamples(Array.isArray(sampleProducts) ? sampleProducts : null);
+	const problem = useMemo(() => hostSamples && sampleProblem(hostSamples), [hostSamples]);
+	if (problem && connection === "unbound") throw new Error(problem);
+	useEffect(() => {
+		if (problem && process.env.NODE_ENV !== "production") console.error(`[gd-commerce-storefront] ${problem}`);
+	}, [problem]);
+	const { refresh } = useSampleCart();
+	useEffect(() => {
+		if (hostSamples && !problem && connection === "unbound") refresh(hostSamples);
+	}, [
+		hostSamples,
+		problem,
+		connection,
+		refresh
+	]);
+	const sampleCatalog = useMemo(() => hostSamples ? {
+		source: "sample",
+		samples: hostSamples
+	} : builtInCatalog, [hostSamples]);
 	let content;
 	if (connection === "ready") content = /* @__PURE__ */ jsx(CatalogLoader, {
 		className,
@@ -2345,7 +2488,7 @@ function CatalogRoot({ children, className, sampleProducts: sampleProducts$1 = f
 		urlState,
 		children
 	});
-	else if (connection === "unbound" && sampleProducts$1) content = /* @__PURE__ */ jsx(CatalogContext.Provider, {
+	else if (connection === "unbound" && sampleProducts) content = /* @__PURE__ */ jsx(CatalogContext.Provider, {
 		value: sampleCatalog,
 		children: /* @__PURE__ */ jsx("section", {
 			...partProps("catalog-root", className),
@@ -2362,6 +2505,13 @@ function CatalogRoot({ children, className, sampleProducts: sampleProducts$1 = f
 		children: content
 	}) });
 }
+/** The previous list while the samples and their fields are unchanged, so an inline list does not rebuild the cards. */
+function useStableSamples(samples) {
+	const [stable, setStable] = useState(samples);
+	const same = stable === samples || !!stable && !!samples && sameSamples(stable, samples);
+	if (!same) setStable(samples);
+	return same ? stable : samples;
+}
 function CatalogLoader({ children, className, pageSize, urlState }) {
 	const { config } = useCommerce();
 	const [params, setParams] = useRootParams(urlState);
@@ -2451,13 +2601,6 @@ function summary(catalog) {
 }
 /** Two columns on phones, then as many 240px columns as fit. Shared with `RelatedProducts`. */
 const catalogGridClass = "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";
-const sampleItems = sampleProducts.map((sample) => ({
-	key: sample.key,
-	item: {
-		source: "sample",
-		sample
-	}
-}));
 const packagedCard$1 = /* @__PURE__ */ jsx(ProductCardRoot, {
 	className: packagedCardClass,
 	children: /* @__PURE__ */ jsx(PackagedCardParts, {})
@@ -2471,13 +2614,20 @@ function CatalogProducts({ className, children }) {
 	const customEmpty = useContext(CatalogEmptyContext)?.custom ?? false;
 	const card = hasChildren(children) ? children : packagedCard$1;
 	const nodes = catalog.source === "live" ? catalog.nodes : null;
+	const samples = catalog.source === "sample" ? catalog.samples : null;
 	const items = useMemo(() => nodes ? nodes.map((product) => ({
 		key: product.id ?? "",
 		item: {
 			source: "live",
 			product
 		}
-	})) : sampleItems, [nodes]);
+	})) : (samples ?? []).map((sample) => ({
+		key: sample.key,
+		item: {
+			source: "sample",
+			sample
+		}
+	})), [nodes, samples]);
 	const products = catalog.source === "live" ? catalog.products : null;
 	const { messages } = useCommerce();
 	const text = useMessage();
@@ -2506,7 +2656,7 @@ function CatalogProducts({ className, children }) {
 				"aria-hidden": "true",
 				className: "motion-safe:animate-pulse",
 				children: [
-					/* @__PURE__ */ jsx("div", { className: "aspect-square bg-commerce-tint-strong" }),
+					/* @__PURE__ */ jsx("div", { className: "aspect-(--commerce-card-image-aspect,1/1) bg-commerce-tint-strong" }),
 					/* @__PURE__ */ jsxs("div", {
 						className: "space-y-2 pt-3",
 						children: [/* @__PURE__ */ jsx("div", { className: "h-4 w-2/3 rounded bg-commerce-tint-strong" }), /* @__PURE__ */ jsx("div", { className: "h-4 w-1/4 rounded bg-commerce-tint-strong" })]
@@ -2566,9 +2716,9 @@ function CatalogPagination({ className }) {
 	});
 }
 /** The packaged catalog. Compose `CatalogRoot` and the catalog parts for a custom layout. */
-function Catalog({ title, description, showHeader = true, sampleProducts: sampleProducts$1, pageSize }) {
+function Catalog({ title, description, showHeader = true, sampleProducts, pageSize }) {
 	return /* @__PURE__ */ jsxs(CatalogRoot, {
-		sampleProducts: sampleProducts$1,
+		sampleProducts,
 		pageSize,
 		children: [
 			/* @__PURE__ */ jsxs("div", {
@@ -3494,4 +3644,4 @@ function RelatedProducts({ productId: productIdProp, title, limit = 4, className
 }
 
 //#endregion
-export { AddToCartButton, ApiError, CartButton, CartCheckout, CartCheckoutNote, CartClose, CartContinueShopping, CartDescription, CartDrawer, CartDrawerRoot, CartEmpty, CartItemImage, CartItemName, CartItemOptions, CartItemPrice, CartItemQuantity, CartItemRemove, CartItemRoot, CartItems, CartNotices, CartRoot, CartSubtotal, CartSummary, CartTitle, Catalog, CatalogEmpty, CatalogHeader, CatalogPagination, CatalogProducts, CatalogRoot, CatalogSummary, CommerceProvider, CommerceStatus, CommerceStorefront, ProductCard, ProductCardAction, ProductCardBadge, ProductCardDescription, ProductCardImage, ProductCardPrice, ProductCardRoot, ProductCardSwatches, ProductCardTitle, ProductDetails, ProductDetailsAddToCart, ProductDetailsAvailability, ProductDetailsBackLink, ProductDetailsBadge, ProductDetailsDescription, ProductDetailsGallery, ProductDetailsOption, ProductDetailsOptions, ProductDetailsPrice, ProductDetailsPurchase, ProductDetailsPurchaseStatus, ProductDetailsQuantity, ProductDetailsRoot, ProductDetailsTitle, ProductImage, RelatedProducts, enUS, formatMessage, getAvailableInventoryQuantity, getCartSummaryTotals, getImageUrls, getLabeledSkuOptions, getPrimaryImageUrl, getProductAttributes, getSingleMatchedSku, money, moneyRange, useCart, useCartItem, useCommerce, useMessage, useMoney, useMoneyRange, useProductCard, useProductDetails, useProductDetailsOption };
+export { AddToCartButton, ApiError, CartButton, CartCheckout, CartCheckoutNote, CartClose, CartContinueShopping, CartDescription, CartDrawer, CartDrawerRoot, CartEmpty, CartItemImage, CartItemName, CartItemOptions, CartItemPrice, CartItemQuantity, CartItemRemove, CartItemRoot, CartItems, CartNotices, CartRoot, CartSubtotal, CartSummary, CartTitle, Catalog, CatalogEmpty, CatalogHeader, CatalogPagination, CatalogProducts, CatalogRoot, CatalogSummary, CommerceProvider, CommerceStatus, CommerceStorefront, ProductCard, ProductCardAction, ProductCardBadge, ProductCardDescription, ProductCardImage, ProductCardPrice, ProductCardRoot, ProductCardSwatches, ProductCardTitle, ProductDetails, ProductDetailsAddToCart, ProductDetailsAvailability, ProductDetailsBackLink, ProductDetailsBadge, ProductDetailsDescription, ProductDetailsGallery, ProductDetailsOption, ProductDetailsOptions, ProductDetailsPrice, ProductDetailsPurchase, ProductDetailsPurchaseStatus, ProductDetailsQuantity, ProductDetailsRoot, ProductDetailsTitle, ProductImage, RelatedProducts, enUS, formatMessage, getAvailableInventoryQuantity, getCartSummaryTotals, getImageUrls, getLabeledSkuOptions, getPrimaryImageUrl, getProductAttributes, getSingleMatchedSku, money, moneyRange, useCart, useCartItem, useCatalog, useCommerce, useMessage, useMoney, useMoneyRange, useProductCard, useProductDetails, useProductDetailsOption };

package/dist/styles.css

@@ -311,6 +311,9 @@
 .commerce-storefront .inline-flex {
     display: inline-flex;
   }
+.commerce-storefront .aspect-\(--commerce-card-image-aspect\,1\/1\) {
+    aspect-ratio: var(--commerce-card-image-aspect,1/1);
+  }
 .commerce-storefront .aspect-square {
     aspect-ratio: 1 / 1;
   }

package/package.json

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