@godaddy/gd-commerce-storefront 0.5.0 → 0.7.0

package/dist/index.d.ts

@@ -13,7 +13,8 @@ declare class ApiError extends Error {
   readonly status: number;
   constructor(message: string, status: number, options?: ErrorOptions);
 }
-declare function money(value: number, currency: string): string;
+/** Formats minor units, such as cents, as currency. Inside the provider, prefer `useMoney`, which follows its `locale`. */
+declare function money(value: number, currency: string, locale?: string): string;
 //#endregion
 //#region src/cart-model.d.ts
 interface Money {
@@ -303,18 +304,60 @@ declare function getPrimaryImageUrl(item: MediaObjectContainer | null | undefine
 declare function getProductAttributes(skuGroup: SKUGroup | null | undefined): StorefrontProductAttribute[];
 /** The product's display name: its label, then its name. */
 declare function getProductName(skuGroup: SKUGroup): string;
+/** Lowercases a label for use mid-sentence, leaving acronyms alone: "Size" becomes "size", "US Size" stays. */
+declare const inSentence: (label: string) => string;
+/** Whether `compareAt` is above `price`, so the price is a sale price. */
+declare function isOnSale(price: number | null | undefined, compareAt: number | null | undefined): boolean;
+/**
+ * Whether some SKU's compare-at price is above that SKU's own price. Without every SKU's price, only a product whose
+ * lowest compare-at price is above its highest price is certainly on sale, so other products show no badge.
+ */
+declare function isProductOnSale(product: SKUGroup | null | undefined): boolean;
+/**
+ * The compare-at price that belongs with the product's starting price, so a struck-through price never pairs one
+ * SKU's price with another SKU's compare-at price. With every SKU and its price loaded, the cheapest SKUs must share
+ * one compare-at price above their price. Otherwise the product needs a single price and a single compare-at price.
+ */
+declare function getStartingCompareAt(product: SKUGroup | null | undefined): number | null;
+/** The SKU's attribute value names, or `null` when the response does not include them. */
+declare function getSkuAttributeValueNames(sku: SKU | null | undefined): string[] | null;
+//#endregion
+//#region src/part.d.ts
+/** Replacement content for a part's text: content, or a function of the part's state. */
+type PartLabel<State> = ReactNode | ((state: State) => ReactNode);
 //#endregion
 //#region src/cart.d.ts
-declare function CartButton(): ReactElement;
-declare function AddToCartButton({
-  sku,
-  name,
-  quantity
-}: {
+interface CartButtonProps {
+  /**
+   * Replaces the bag icon and count badge with a visible label. A function receives the item count. Keep the count in
+   * the label.
+   */
+  children?: PartLabel<{
+    itemCount: number;
+  }>;
+}
+/**
+ * Opens the cart drawer: a bag icon with a count badge that pops when the count changes. Its accessible name is
+ * "Cart, 2 items". With `children`, a labeled button instead.
+ */
+declare function CartButton({
+  children
+}?: CartButtonProps): ReactElement;
+/** What an add-to-cart label can depend on. */
+interface AddToCartLabelState {
+  /** The add is running. */
+  readonly busy: boolean;
+  /** Tracked stock is used up, so the button stays disabled. */
+  readonly soldOut: boolean;
+}
+interface AddToCartButtonProps {
   sku: SKU;
   name: string;
   quantity?: number;
-}): ReactElement;
+  /** Replaces the label. A function receives `busy` and `soldOut`; the button keeps its rules either way. */
+  children?: PartLabel<AddToCartLabelState>;
+}
+declare function AddToCartButton(props: AddToCartButtonProps): ReactElement;
 //#endregion
 //#region src/cart-state.d.ts
 /** One cart line, for custom cart parts. */
@@ -351,6 +394,20 @@ declare function useCart(): CartState;
 interface CartPartProps {
   className?: string;
 }
+/** Props for a cart part whose text the host can replace, with or without the sample wording. */
+interface CartTextPartProps extends CartPartProps {
+  /** Replaces the text. A function receives whether the cart is the sample cart. */
+  children?: PartLabel<{
+    isSample: boolean;
+  }>;
+}
+/** Props for a cart button whose label the host can replace. The button keeps its behavior and state. */
+interface CartActionPartProps extends CartPartProps {
+  /** Replaces the button label. A function receives whether the action is running. */
+  children?: PartLabel<{
+    busy: boolean;
+  }>;
+}
 interface CartRootProps {
   children: ReactNode;
   /** Added to the root `<section>`. */
@@ -378,14 +435,19 @@ 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. */
+/**
+ * "Your cart", or "Sample cart" before a store is connected, as an H2, with the item count once there are items.
+ * In the drawer it names the dialog.
+ */
 declare function CartTitle({
-  className
-}: CartPartProps): ReactElement;
+  className,
+  children
+}: CartTextPartProps): ReactElement;
 /** One line about the cart. In the drawer it describes the dialog. */
 declare function CartDescription({
-  className
-}: CartPartProps): ReactElement;
+  className,
+  children
+}: CartTextPartProps): ReactElement;
 /** The drawer's close button. Renders nothing outside the drawer. */
 declare function CartClose({
   className
@@ -426,7 +488,7 @@ declare function CartItemImage({
 declare function CartItemName({
   className
 }: CartPartProps): ReactElement;
-/** The selected options, one per line, such as "Color: Blue". Renders nothing without options. */
+/** The selected options on one line, such as "Color: Blue · Size: M". Renders nothing without options. */
 declare function CartItemOptions({
   className
 }: CartPartProps): ReactElement | null;
@@ -440,8 +502,9 @@ declare function CartItemQuantity({
 }: CartPartProps): ReactElement;
 /** Removes the line. */
 declare function CartItemRemove({
-  className
-}: CartPartProps): ReactElement;
+  className,
+  children
+}: CartActionPartProps): ReactElement;
 interface CartEmptyProps extends CartPartProps {
   /** Replaces the default message and link. */
   children?: ReactNode;
@@ -464,7 +527,7 @@ declare function CartSubtotal({
   className
 }: CartPartProps): ReactElement | null;
 /**
- * "Shipping, taxes, and discounts are calculated at checkout." Has the stable
+ * A row under the subtotal: "Shipping, taxes & discounts", "Calculated at checkout". Has the stable
  * `commerce-cart-checkout-adjustments-note` class. Renders nothing for samples or an empty cart.
  */
 declare function CartCheckoutNote({
@@ -475,8 +538,17 @@ declare function CartCheckoutNote({
  * Samples never check out. Renders nothing for an empty cart.
  */
 declare function CartCheckout({
-  className
-}: CartPartProps): ReactElement | null;
+  className,
+  children
+}: CartActionPartProps): ReactElement | null;
+/**
+ * "Continue shopping": closes the drawer, or on a cart page links to the catalog. Renders nothing for an empty cart,
+ * whose `CartEmpty` links to the catalog.
+ */
+declare function CartContinueShopping({
+  className,
+  children
+}: CartTextPartProps): ReactElement | null;
 /** The packaged cart drawer. Compose `CartDrawerRoot` and the cart parts for a custom drawer. */
 declare function CartDrawer(): ReactElement;
 //#endregion
@@ -491,12 +563,21 @@ interface CatalogRootProps {
   className?: string;
   /** Permit built-in examples only while the host confirms this site is unbound. */
   sampleProducts?: boolean;
+  /** Products per page, a whole number of 1 or more. Defaults to 6. Samples are always one page of six. */
+  pageSize?: number;
+  /**
+   * Keep the page cursor in the page URL, as `after`, so a reload or a shared link keeps the page. Defaults to
+   * `true`. Set `false` for every other catalog on the same page, so the catalogs do not share one cursor.
+   */
+  urlState?: boolean;
 }
 /** Loads one cursor page of products, or the built-in samples, and provides them to catalog parts. */
 declare function CatalogRoot({
   children,
   className,
-  sampleProducts
+  sampleProducts,
+  pageSize,
+  urlState
 }: CatalogRootProps): ReactElement;
 interface CatalogHeaderProps extends CatalogPartProps {
   title?: string;
@@ -518,13 +599,27 @@ interface CatalogProductsProps extends CatalogPartProps {
 }
 /**
  * The product cards. `className` goes on the element that contains the cards, such as a grid. While loading, that
- * element holds placeholder cards. The error with its retry and the empty message render just before it.
+ * element holds placeholder cards. The error with its retry and, without a `CatalogEmpty`, the empty message render just before it.
  */
 declare function CatalogProducts({
   className,
   children
 }: CatalogProductsProps): ReactElement;
-/** First-page and next-page buttons. Renders nothing for samples, which have one page. */
+interface CatalogEmptyProps extends CatalogPartProps {
+  /** Replaces the default message. */
+  children?: ReactNode;
+}
+/**
+ * Renders only when a connected store's catalog has no products: "No products available.", or its children. While
+ * one is mounted, `CatalogProducts` leaves out its own empty message. Samples are never empty.
+ */
+declare function CatalogEmpty({
+  className,
+  children
+}: CatalogEmptyProps): ReactElement | null;
+/**
+ * First-page and next-page buttons. Renders nothing when there is only one page, including for samples.
+ */
 declare function CatalogPagination({
   className
 }: CatalogPartProps): ReactElement | null;
@@ -537,13 +632,16 @@ interface CatalogProps {
   showHeader?: boolean;
   /** Permit built-in examples only while the host confirms this site is unbound. */
   sampleProducts?: boolean;
+  /** Products per page. Defaults to 6. */
+  pageSize?: number;
 }
 /** The packaged catalog. Compose `CatalogRoot` and the catalog parts for a custom layout. */
 declare function Catalog({
   title,
   description,
   showHeader,
-  sampleProducts
+  sampleProducts,
+  pageSize
 }: CatalogProps): ReactElement;
 //#endregion
 //#region src/commerce-provider.d.ts
@@ -552,7 +650,11 @@ interface CommerceContextValue {
   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;
   cart: CartOrder | null;
   /** Whether the cart drawer is open. Always `false` when no `CartDrawer` or `CartDrawerRoot` is mounted. */
   open: boolean;
@@ -573,6 +675,11 @@ interface CommerceContextValue {
   checkout: () => Promise<boolean>;
 }
 declare function useCommerce(): CommerceContextValue;
+/**
+ * Formats minor units, such as cents, in the provider's `locale`, the way the package's own parts do. Uses the
+ * store's currency unless `currency` is given.
+ */
+declare function useMoney(): (value: number, currency?: string) => string;
 type StorefrontTheme = CSSProperties & {
   '--commerce-accent'?: string;
   '--commerce-accent-hover'?: string;
@@ -580,21 +687,83 @@ type StorefrontTheme = CSSProperties & {
   '--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: localized text will be a separate, opt-in prop, so setting `locale` cannot change wording.
+   */
+  locale?: string;
   /**
    * Called after an item is added, live or sample. With a drawer mounted, the drawer also opens. Without one, such as
    * on a site with a cart page, use it to confirm the add.
    */
   onItemAdded?: (item: AddedCartItem) => void;
+  /** Called for every cart change and failure, such as for analytics. See `CommerceEvent`. */
+  onEvent?: (event: CommerceEvent) => void;
 }
+/** A cart operation that can fail. */
+type CommerceOperation = 'add' | 'change-quantity' | 'remove' | 'discount' | 'refresh' | 'checkout';
+/**
+ * What `onEvent` reports. Live changes are reported once the server returns the updated cart; sample changes have
+ * `isSample: true` and never reach the store. New event types may be added, so ignore types you do not handle.
+ */
+type CommerceEvent = {
+  readonly type: 'item-added';
+  /** `null` for a sample product, which is not a SKU. */
+  readonly skuId: string | null;
+  readonly name: string;
+  readonly quantity: number;
+  readonly isSample: boolean;
+} | {
+  readonly type: 'quantity-changed';
+  readonly itemId: string;
+  readonly quantity: number;
+  readonly isSample: boolean;
+} | {
+  readonly type: 'item-removed';
+  readonly itemId: string;
+  readonly isSample: boolean;
+} | {
+  readonly type: 'discount-applied';
+  readonly code: string;
+}
+/** Sent just before the browser leaves for checkout. */ | {
+  readonly type: 'checkout-started';
+  readonly cartId: string;
+}
+/** `message` is the one the cart shows. */ | {
+  readonly type: 'error';
+  readonly operation: CommerceOperation;
+  readonly message: string;
+};
 /** The item passed to `onItemAdded`. */
 interface AddedCartItem {
   readonly name: string;
@@ -608,7 +777,10 @@ declare function CommerceProvider({
   productPath,
   checkoutSuccessPath,
   theme,
-  onItemAdded
+  getSwatch,
+  locale,
+  onItemAdded,
+  onEvent
 }: CommerceProviderProps): ReactElement;
 //#endregion
 //#region src/commerce-storefront.d.ts
@@ -619,6 +791,22 @@ declare function CommerceStorefront({
 }: CommerceProviderProps): react_jsx_runtime0.JSX.Element;
 //#endregion
 //#region src/product-card.d.ts
+interface ProductImageProps {
+  url?: string | null;
+  /** The alt text. Pass `''` for a decorative image, such as a thumbnail next to the product name. */
+  name: string;
+  /** Added to the image, or to its placeholder. */
+  className?: string;
+}
+/**
+ * A product image that fills its container, with a labeled placeholder when there is no URL or it fails to load.
+ * Use it in custom parts so they handle missing images like the package's own.
+ */
+declare function ProductImage({
+  url,
+  name,
+  className
+}: ProductImageProps): ReactElement;
 /** Read-only card state for custom parts rendered inside `ProductCardRoot`. */
 interface ProductCardState {
   /** `null` for a built-in sample, which is not a catalog product. */
@@ -662,17 +850,41 @@ declare function ProductCardTitle({
 declare function ProductCardDescription({
   className
 }: ProductCardPartProps): ReactElement | null;
-/** The product's price, or its price range when variants differ. */
+/**
+ * "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.
+ */
+declare function ProductCardBadge({
+  className
+}: ProductCardPartProps): ReactElement | null;
+/** The product's price, or its price range when variants differ. A single price on sale shows its compare-at price. */
 declare function ProductCardPrice({
   className
 }: ProductCardPartProps): ReactElement;
+/**
+ * Dots for the first attribute whose values all have a swatch from the provider's `getSwatch`, such as colors.
+ * Renders nothing without `getSwatch`, for samples, or when no attribute has swatches.
+ */
+declare function ProductCardSwatches({
+  className
+}: ProductCardPartProps): ReactElement | null;
+/** What a card action label can depend on. Only `add` can be busy or sold out. */
+interface ProductCardActionLabelState extends AddToCartLabelState {
+  /** `add` adds directly; `choose-options` and `view-product` link to the product page. */
+  readonly action: 'add' | 'choose-options' | 'view-product';
+}
+interface ProductCardActionProps extends ProductCardPartProps {
+  /** Replaces the button or link label. A function receives the action and its state. */
+  children?: PartLabel<ProductCardActionLabelState>;
+}
 /**
  * Adds the product directly when it has exactly one SKU and no options; otherwise links to its page to choose.
  * Samples add to the sample cart.
  */
 declare function ProductCardAction({
-  className
-}: ProductCardPartProps): ReactElement;
+  className,
+  children
+}: ProductCardActionProps): ReactElement;
 interface ProductCardProps {
   product: SKUGroup;
 }
@@ -706,11 +918,20 @@ interface ProductDetailsOptionValueState {
   readonly name: string;
   readonly label: string;
   readonly selected: boolean;
+  /**
+   * Every SKU with this value and the other selected values has tracked stock used up. `false` when that is not
+   * known, such as for a product with more SKUs than the page loads.
+   */
+  readonly soldOut: boolean;
+  /** The CSS background from the provider's `getSwatch`, or `null`. */
+  readonly swatch: string | null;
 }
 interface ProductDetailsOptionState {
   readonly name: string;
   readonly label: string;
   readonly selected: string | null;
+  /** Nothing is selected and the shopper pressed add, so the control should show an error. */
+  readonly missing: boolean;
   readonly values: readonly ProductDetailsOptionValueState[];
   /** Accepts only this attribute's own value names, or `null` to clear. Other values are ignored. */
   readonly select: (value: string | null) => void;
@@ -724,28 +945,64 @@ interface ProductDetailsRootProps {
   children: ReactNode;
   /** Added to the root `<article>`. */
   className?: string;
-}
-/** Loads the product for the route's `:productId` and provides state to product parts. */
+  /** The product to show. Defaults to the route's `:productId` parameter. */
+  productId?: string;
+  /**
+   * Keep the selected options and SKU in the page URL, as `option.<attribute>` and `sku`, so a reload or a shared link
+   * keeps them. Defaults to `true`. Set `false` for every other root on the same page, such as a quick view, so the
+   * roots do not share one selection.
+   */
+  urlState?: boolean;
+  /** Replaces the loading message. */
+  loading?: ReactNode;
+  /** Replaces the not-found heading and link. */
+  notFound?: ReactNode;
+  /** Replaces the load failure. A function receives the failure message and a `retry` for the product request. */
+  error?: PartLabel<ProductDetailsErrorState>;
+}
+/** What a replacement for the product load failure receives. */
+interface ProductDetailsErrorState {
+  readonly message: string;
+  readonly retry: () => void;
+}
+/** Loads one product, by default the route's `:productId`, and provides state to product parts. */
 declare function ProductDetailsRoot({
-  children,
-  className
+  productId: productIdProp,
+  className,
+  ...props
 }: ProductDetailsRootProps): ReactElement;
 //#endregion
 //#region src/product-details.d.ts
 /** The packaged product page for `${productPath}/:productId`. Compose the parts for a custom layout. */
 declare function ProductDetails(): ReactElement;
+interface ProductDetailsBackLinkProps extends ProductDetailsPartProps {
+  /** Replaces the chevron and "Back to shop". */
+  children?: ReactNode;
+}
+/** A link to the catalog. */
 declare function ProductDetailsBackLink({
-  className
-}: ProductDetailsPartProps): ReactElement;
+  className,
+  children
+}: ProductDetailsBackLinkProps): ReactElement;
 /** Main image with thumbnails; the selected SKU's images replace the product's when present. */
 declare function ProductDetailsGallery({
   className
 }: ProductDetailsPartProps): ReactElement;
+/**
+ * "Sale" when the verified SKU's compare-at price is above its price, or, before then, when some SKU's is. Renders
+ * nothing otherwise.
+ */
+declare function ProductDetailsBadge({
+  className
+}: ProductDetailsPartProps): ReactElement | null;
 /** The product name as the page's H1. */
 declare function ProductDetailsTitle({
   className
 }: ProductDetailsPartProps): ReactElement;
-/** The verified SKU's price and compare-at price, or the product's starting price. */
+/**
+ * The verified SKU's price and compare-at price, or the product's starting price. Before a SKU is verified, the
+ * compare-at price shows only when it belongs to the cheapest SKUs, so it never pairs prices from different SKUs.
+ */
 declare function ProductDetailsPrice({
   className
 }: ProductDetailsPartProps): ReactElement;
@@ -755,11 +1012,11 @@ declare function ProductDetailsDescription({
 }: ProductDetailsPartProps): ReactElement;
 //#endregion
 //#region src/product-purchase.d.ts
-/** The packaged purchase area: options, status, availability, quantity, and add to cart. */
+/** The packaged purchase area: options, status, quantity, add to cart, and availability. */
 declare function ProductDetailsPurchase({
   className
 }: ProductDetailsPartProps): ReactElement;
-/** A select for every product attribute, or the SKU list for products without attributes. */
+/** A control for every product attribute, or the SKU list for products without attributes. */
 declare function ProductDetailsOptions({
   className
 }: ProductDetailsPartProps): ReactElement | null;
@@ -767,12 +1024,18 @@ interface ProductDetailsOptionProps extends ProductDetailsPartProps {
   /** The attribute `name`, such as `color`. Renders nothing when the product has no such attribute. */
   attribute: string;
 }
-/** A select for one product attribute. Use `useProductDetailsOption` for swatches or other custom controls. */
+/**
+ * One product attribute: buttons, swatches when the provider's `getSwatch` gives every value one, or a select for
+ * more than eight values. Use `useProductDetailsOption` for other custom controls.
+ */
 declare function ProductDetailsOption({
   attribute,
   className
 }: ProductDetailsOptionProps): ReactElement | null;
-/** The single message explaining why the selection is not yet purchasable. Renders nothing when ready. */
+/**
+ * The single message explaining why the selection is not purchasable. Renders nothing when ready, or before every
+ * option is chosen, when the add button names the next one.
+ */
 declare function ProductDetailsPurchaseStatus({
   className
 }: ProductDetailsPartProps): ReactElement | null;
@@ -780,16 +1043,55 @@ declare function ProductDetailsPurchaseStatus({
 declare function ProductDetailsAvailability({
   className
 }: ProductDetailsPartProps): ReactElement | null;
-/** Quantity for the verified SKU, with a message when it cannot be added. Renders nothing until a SKU is verified. */
+/**
+ * A quantity stepper, capped at the verified SKU's stock, with a message when a typed quantity cannot be added.
+ * Disabled while the verified SKU is sold out.
+ */
 declare function ProductDetailsQuantity({
   className
-}: ProductDetailsPartProps): ReactElement | null;
-/** Adds the verified SKU and quantity. While disabled, its accessible description says why. */
-declare function ProductDetailsAddToCart({
-  className
 }: ProductDetailsPartProps): ReactElement;
+interface ProductDetailsAddToCartProps extends ProductDetailsPartProps {
+  /** Replaces the button label. A function receives `busy` and `soldOut`; the button keeps its rules either way. */
+  children?: PartLabel<AddToCartLabelState>;
+}
+/**
+ * Adds the verified SKU and quantity, labeled with the total, such as "Add to cart · $64.00". Until every option is
+ * chosen it names the next one, such as "Select size", and pressing it marks the missing options and focuses the
+ * first. While the selection is checked or unavailable it is disabled, and its accessible description says why.
+ */
+declare function ProductDetailsAddToCart({
+  className,
+  children
+}: ProductDetailsAddToCartProps): ReactElement;
+//#endregion
+//#region src/related-products.d.ts
+interface RelatedProductsProps {
+  /** The product to leave out. Defaults to the route's `:productId` parameter. */
+  productId?: string;
+  /** The H2. Defaults to "You may also like". */
+  title?: ReactNode;
+  /** The most products to show, a whole number from 1 to 24. Defaults to 4. */
+  limit?: number;
+  /** Added to the root `<section>`. */
+  className?: string;
+  /** One card, rendered for every product. Defaults to the packaged card. */
+  children?: ReactNode;
+}
+/**
+ * Other products from the catalog's first page, leaving out the current one. Optional and separate from
+ * `ProductDetails`: place it wherever it fits, such as after the product page. There is no related-products API, so
+ * the products are the catalog's first ones. Renders nothing until they load, when none are left, if the request
+ * fails, or while no store is connected.
+ */
+declare function RelatedProducts({
+  productId: productIdProp,
+  title,
+  limit,
+  className,
+  children
+}: RelatedProductsProps): ReactElement | null;
 //#endregion
 //#region src/storefront-surface.d.ts
 declare function CommerceStatus(): ReactElement | null;
 //#endregion
-export { AddToCartButton, AddToCartItemInput, type AddedCartItem, ApiError, CartAddress, CartButton, CartCheckout, CartCheckoutNote, CartClose, CartDescription, CartDiscount, CartDrawer, CartDrawerRoot, type CartDrawerRootProps, CartEmpty, type CartEmptyProps, CartItemImage, CartItemName, CartItemOptions, CartItemPrice, CartItemQuantity, CartItemRemove, CartItemRoot, type CartItemRootProps, type CartItemState, CartItems, type CartItemsProps, CartLineItem, CartLineItemDetails, CartNote, CartNotices, CartOrder, type CartPartProps, CartRoot, type CartRootProps, CartSelectedAddon, CartSelectedAddonValue, CartSelectedOption, CartShippingInfo, type CartState, CartSubtotal, CartSummary, type CartSummaryProps, CartSummaryTotals, CartTax, CartTitle, Catalog, CatalogHeader, type CatalogHeaderProps, CatalogPagination, type CatalogPartProps, CatalogProducts, type CatalogProductsProps, type CatalogProps, CatalogRoot, type CatalogRootProps, CatalogSummary, type CommerceContextValue, CommerceProvider, type CommerceProviderProps, CommerceStatus, CommerceStorefront, Connection, ConnectionEdge, DraftOrderContext, InventoryCount, LabelFilter, LineItemTotals, MediaObject, Money, OrderTotals, PageInfo, PriceRange, ProductCard, ProductCardAction, ProductCardDescription, ProductCardImage, type ProductCardPartProps, ProductCardPrice, type ProductCardProps, ProductCardRoot, type ProductCardRootProps, type ProductCardState, ProductCardTitle, ProductDetails, ProductDetailsAddToCart, ProductDetailsAvailability, ProductDetailsBackLink, ProductDetailsDescription, ProductDetailsGallery, ProductDetailsOption, type ProductDetailsOptionProps, type ProductDetailsOptionState, type ProductDetailsOptionValueState, ProductDetailsOptions, type ProductDetailsPartProps, ProductDetailsPrice, ProductDetailsPurchase, ProductDetailsPurchaseStatus, ProductDetailsQuantity, ProductDetailsRoot, type ProductDetailsRootProps, type ProductDetailsState, type ProductDetailsStatus, ProductDetailsTitle, ProductDetailsVariablesInput, ProductGridVariablesInput, SKU, SKUAttributeValue, SKUGroup, SKUGroupAttribute, SKUGroupAttributeValue, SKUGroupSKU, SKUPrice, SkuGroupResult, SkuGroupVariables, SkuGroupsResult, SkuGroupsVariables, SkuResult, SkuVariables, type StorefrontConfig, StorefrontProductAttribute, StorefrontProductAttributeValue, type StorefrontTheme, StringInFilter, addToCart, getAvailableInventoryQuantity, getCartSummaryTotals, getImageUrls, getLabeledSkuOptions, getPrimaryImageUrl, getProductAttributes, getProductName, getSingleMatchedSku, getSingleMatchedSkuId, money, useCart, useCartItem, useCommerce, useProductCard, useProductDetails, useProductDetailsOption };
+export { AddToCartButton, type AddToCartButtonProps, AddToCartItemInput, type AddToCartLabelState, type AddedCartItem, ApiError, type CartActionPartProps, CartAddress, CartButton, type CartButtonProps, CartCheckout, CartCheckoutNote, CartClose, 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 CommerceEvent, type CommerceOperation, CommerceProvider, type CommerceProviderProps, CommerceStatus, CommerceStorefront, Connection, ConnectionEdge, DraftOrderContext, type GetSwatch, InventoryCount, LabelFilter, LineItemTotals, MediaObject, 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, StorefrontProductAttribute, StorefrontProductAttributeValue, type StorefrontTheme, StringInFilter, type SwatchValue, addToCart, getAvailableInventoryQuantity, getCartSummaryTotals, getImageUrls, getLabeledSkuOptions, getPrimaryImageUrl, getProductAttributes, getProductName, getSingleMatchedSku, getSingleMatchedSkuId, getSkuAttributeValueNames, getStartingCompareAt, inSentence, isOnSale, isProductOnSale, money, useCart, useCartItem, useCommerce, useMoney, useProductCard, useProductDetails, useProductDetailsOption };