@godaddy/gd-commerce-storefront 0.3.0 → 0.4.0

package/README.md

@@ -100,9 +100,10 @@ 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, with `title`, `description`, and `showHeader` props |
+| `CatalogRoot` and catalog parts | Build a [custom catalog or card layout](#custom-catalog-layouts) with the same rules as `Catalog` |
 | `ProductDetails` | Reads `:productId`; validates URL option selections against catalog results |
 | `ProductDetailsRoot` and product parts | Build a [custom product layout](#custom-product-layouts) with the same rules as `ProductDetails` |
-| `ProductCard` | Renders one `SKUGroup` with direct add or a product-details link |
+| `ProductCard` | Renders one `SKUGroup` with direct add or a product-details link; `ProductCardRoot` and card parts customize it |
 | `CartButton` | Opens the shared drawer and displays item count |
 | `AddToCartButton` | Adds a verified `sku`, `name`, and optional integer `quantity` |
 | `CommerceStatus` | Connection progress/error/retry for custom layouts |
@@ -153,7 +154,7 @@ Every part is named `ProductDetails*` because it works only inside `ProductDetai
 
 Parts read state from the root and take no product, SKU, price or quantity props. Whatever the layout, only a server-verified SKU can be added, and changing a selection resets the quantity and image. Every part throws if it is rendered outside `ProductDetailsRoot`. In development builds, if no control is rendered for an attribute the product requires, a console warning names the missing ones. A control that mounts later, such as one in a closed accordion, can trigger it; the product becomes purchasable once the control renders. Products without attributes but with several SKUs need `ProductDetailsOptions` or `ProductDetailsPurchase`. Parts can be rendered more than once, such as in a sticky mobile purchase bar; each copy gets its own element IDs.
 
-Every part accepts `className`, which is added to the part's outer element, a wrapper the package's CSS reset leaves alone. Host classes there control margin, padding, border, color, width and grid placement, including layered utilities such as Tailwind v4's. The packaged layout sets its spacing and grid placement this way. Elements inside the part, such as the title's `<h1>`, keep the package's own styles: a host font size on `ProductDetailsTitle` does not change the heading's size, but a host color does reach it, because the heading inherits its color.
+Every part accepts `className`, which is added to the part's outer element, a wrapper the package's CSS reset leaves alone. Host classes there control margin, padding, border, color, width, display, gap and grid placement, including layered utilities such as Tailwind v4's. In `ProductDetailsOptions` and `ProductDetailsPurchase`, each control keeps a 24px bottom margin, even in a host grid. The exception is a class name the package also uses, such as `grid-cols-1` or `p-6`: the package's rule wins, even over the host's responsive variants on the same element, such as `md:grid-cols-4`. The packaged layout sets its spacing and grid placement this way. Elements inside the part, such as the title's `<h1>`, keep the package's own styles: a host font size on `ProductDetailsTitle` does not change the heading's size, but a host color does reach it, because the heading inherits its color.
 
 Two hooks support custom parts inside the root:
 
@@ -178,6 +179,54 @@ function ColorSwatches() {
 
 Parts are flat named exports, not properties such as `ProductDetails.Title`, so each one is an ordinary module export.
 
+## Custom catalog layouts
+
+`Catalog` is the recommended catalog. When its layout or its cards do not fit, compose the same parts inside `CatalogRoot`. The root loads one cursor page of six products, or the built-in samples when `sampleProducts` is set and no store is connected, and shows the connection state itself. This is `<Catalog sampleProducts />` written out with its packaged card:
+
+```tsx
+import {
+  CatalogHeader, CatalogPagination, CatalogProducts, CatalogRoot, CatalogSummary, ProductCardAction,
+  ProductCardDescription, ProductCardImage, ProductCardPrice, ProductCardRoot, ProductCardTitle,
+} from '@godaddy/gd-commerce-storefront';
+
+<CatalogRoot sampleProducts>
+  <CatalogHeader className='border-b border-neutral-200 pb-10 pt-4 sm:pb-14 sm:pt-8' />
+  <CatalogSummary className='border-b border-neutral-200 py-6 sm:py-8' />
+  <CatalogProducts className='grid grid-cols-1 gap-6 py-8 sm:grid-cols-2 lg:grid-cols-3 lg:gap-8 lg:py-10'>
+    <ProductCardRoot className='flex min-w-0 flex-col overflow-hidden rounded-lg border border-neutral-200'>
+      <ProductCardImage />
+      <div className='flex flex-1 flex-col p-6'>
+        <ProductCardTitle />
+        <ProductCardDescription className='mt-3' />
+        <div className='mt-auto pt-6'>
+          <div className='flex flex-wrap items-end justify-between gap-4 border-t border-neutral-200 pt-5'>
+            <ProductCardPrice className='min-w-0 flex-1' />
+            <ProductCardAction className='max-w-full' />
+          </div>
+        </div>
+      </div>
+    </ProductCardRoot>
+  </CatalogProducts>
+  <CatalogPagination className='border-t border-neutral-200 pt-6' />
+</CatalogRoot>
+```
+
+As with product layouts, the grid, spacing and border classes come from your own stylesheet in a custom layout. Without them, the cards stack in one column.
+
+| Part | Renders |
+| --- | --- |
+| `CatalogHeader` | The `title` as the page's H1 and a `description`; leave it out when the host page owns the H1 |
+| `CatalogSummary` | The loading, failure or product-count status line |
+| `CatalogProducts` | One card per product. Its children are the card, rendered once for each product; without children, the packaged card |
+| `CatalogPagination` | First-page and next-page buttons; nothing for samples |
+| `ProductCardImage`, `ProductCardTitle` | The first image and the name as an H2, each linked to the product page. With a title in the card, keyboard and screen reader users get only the title link; without one, the image link takes its place once the page is interactive |
+| `ProductCardDescription`, `ProductCardPrice` | Up to three lines of description (nothing without one), and the price or price range |
+| `ProductCardAction` | Adds the product directly only when it has one SKU and no options; otherwise links to the product page to choose |
+
+`className` on `CatalogProducts` goes on the element whose direct children are the cards, so a host grid places them, and `className` on `ProductCardRoot` goes on each card, so classes such as `col-span-2` work. The loading placeholder (three cards, one to three columns), the error with its retry button, and the empty message render just before that element, whatever the layout. Card parts take no product, SKU or price props. Inside `CatalogProducts`, `ProductCardRoot` takes no `product` prop either and throws if it gets one, so a card always shows the product it is rendered for. Samples use the same card: they show a placeholder image, no description and no links, and add only to the sample cart. Card and catalog parts throw if they are rendered outside their root. Packaged cards fill their grid row, with the price and action at the bottom of each card.
+
+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).
+
 ## How it works
 
 Products are SKU groups. The package purchases only an unambiguous SKU, verifies all selected attributes through the server, uses SKU prices/images, and distinguishes untracked inventory from sold-out inventory. Server-side inventory and pricing checks remain mandatory.

package/dist/index.d.ts

@@ -301,6 +301,8 @@ declare function getAvailableInventoryQuantity(item: InventoryCountContainer | n
 declare function getImageUrls(item: MediaObjectContainer | null | undefined): string[];
 declare function getPrimaryImageUrl(item: MediaObjectContainer | null | undefined): string | null;
 declare function getProductAttributes(skuGroup: SKUGroup | null | undefined): StorefrontProductAttribute[];
+/** The product's display name: its label, then its name. */
+declare function getProductName(skuGroup: SKUGroup): string;
 //#endregion
 //#region src/cart.d.ts
 declare function CartButton(): ReactElement;
@@ -316,11 +318,53 @@ declare function AddToCartButton({
 declare function CartDrawer(): ReactElement;
 //#endregion
 //#region src/catalog.d.ts
-declare function ProductCard({
-  product
-}: {
-  product: SKUGroup;
-}): ReactElement;
+/** Props shared by every catalog part. `className` is added to the part's outer element. */
+interface CatalogPartProps {
+  className?: string;
+}
+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;
+}
+/** Loads one cursor page of products, or the built-in samples, and provides them to catalog parts. */
+declare function CatalogRoot({
+  children,
+  className,
+  sampleProducts
+}: CatalogRootProps): ReactElement;
+interface CatalogHeaderProps extends CatalogPartProps {
+  title?: string;
+  description?: string;
+}
+/** The catalog title as the page's H1, with a description. */
+declare function CatalogHeader({
+  title,
+  description,
+  className
+}: CatalogHeaderProps): ReactElement;
+/** Announces loading, failure, or how many products the page shows. */
+declare function CatalogSummary({
+  className
+}: CatalogPartProps): ReactElement;
+interface CatalogProductsProps extends CatalogPartProps {
+  /** One card, rendered for every product. Defaults to the packaged card. */
+  children?: ReactNode;
+}
+/**
+ * The product cards. `className` goes on the element that contains the cards, such as a grid. The loading
+ * placeholder, the error with its retry, and the empty message render just before that element.
+ */
+declare function CatalogProducts({
+  className,
+  children
+}: CatalogProductsProps): ReactElement;
+/** First-page and next-page buttons. Renders nothing for samples, which have one page. */
+declare function CatalogPagination({
+  className
+}: CatalogPartProps): ReactElement | null;
 interface CatalogProps {
   title?: string;
   description?: string;
@@ -328,7 +372,13 @@ interface CatalogProps {
   /** Permit built-in examples only while the host confirms this site is unbound. */
   sampleProducts?: boolean;
 }
-declare function Catalog(props: CatalogProps): ReactElement;
+/** The packaged catalog. Compose `CatalogRoot` and the catalog parts for a custom layout. */
+declare function Catalog({
+  title,
+  description,
+  showHeader,
+  sampleProducts
+}: CatalogProps): ReactElement;
 //#endregion
 //#region src/commerce-provider.d.ts
 interface CommerceContextValue {
@@ -387,6 +437,69 @@ declare function CommerceStorefront({
   ...props
 }: CommerceProviderProps): react_jsx_runtime0.JSX.Element;
 //#endregion
+//#region src/product-card.d.ts
+/** Read-only card state for custom parts rendered inside `ProductCardRoot`. */
+interface ProductCardState {
+  /** `null` for a built-in sample, which is not a catalog product. */
+  readonly product: SKUGroup | null;
+  readonly name: string;
+  /** The product page, or `null` for a sample, which has none. */
+  readonly href: string | null;
+  readonly isSample: boolean;
+}
+/** Props shared by every card part. `className` is added to the part's outer element. */
+interface ProductCardPartProps {
+  className?: string;
+}
+/** Read the card's product, name, and link from inside `ProductCardRoot`. */
+declare function useProductCard(): ProductCardState;
+interface ProductCardRootProps {
+  children: ReactNode;
+  /** The catalog product to show. Leave it out inside `CatalogProducts`, which supplies each product. */
+  product?: SKUGroup;
+  /** Added to the root `<article>`. */
+  className?: string;
+}
+/** Provides one product to card parts. Inside `CatalogProducts` it renders the current catalog entry. */
+declare function ProductCardRoot({
+  children,
+  product,
+  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.
+ */
+declare function ProductCardImage({
+  className
+}: ProductCardPartProps): ReactElement;
+/** The product name as an H2, linked to its page. */
+declare function ProductCardTitle({
+  className
+}: ProductCardPartProps): ReactElement;
+/** Up to three lines of the product description. Renders nothing without one. */
+declare function ProductCardDescription({
+  className
+}: ProductCardPartProps): ReactElement | null;
+/** The product's price, or its price range when variants differ. */
+declare function ProductCardPrice({
+  className
+}: ProductCardPartProps): ReactElement;
+/**
+ * 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;
+interface ProductCardProps {
+  product: SKUGroup;
+}
+/** The packaged card for one `SKUGroup`. Compose `ProductCardRoot` and the card parts for a custom card. */
+declare function ProductCard({
+  product
+}: ProductCardProps): ReactElement;
+//#endregion
 //#region src/product-details-context.d.ts
 /** Where the shopper is in choosing a purchasable SKU. Only `ready` has a verified `selectedSku`. */
 type ProductDetailsStatus = 'incomplete' | 'checking' | 'variant-error' | 'unavailable' | 'not-purchasable' | 'ready';
@@ -498,4 +611,4 @@ declare function ProductDetailsAddToCart({
 //#region src/storefront-surface.d.ts
 declare function CommerceStatus(): ReactElement | null;
 //#endregion
-export { AddToCartButton, AddToCartItemInput, ApiError, CartAddress, CartButton, CartDiscount, CartDrawer, CartLineItem, CartLineItemDetails, CartNote, CartOrder, CartSelectedAddon, CartSelectedAddonValue, CartSelectedOption, CartShippingInfo, CartSummaryTotals, CartTax, Catalog, type CatalogProps, type CommerceContextValue, CommerceProvider, type CommerceProviderProps, CommerceStatus, CommerceStorefront, Connection, ConnectionEdge, DraftOrderContext, InventoryCount, LabelFilter, LineItemTotals, MediaObject, Money, OrderTotals, PageInfo, PriceRange, ProductCard, 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, getSingleMatchedSku, getSingleMatchedSkuId, money, useCommerce, useProductDetails, useProductDetailsOption };
+export { AddToCartButton, AddToCartItemInput, ApiError, CartAddress, CartButton, CartDiscount, CartDrawer, CartLineItem, CartLineItemDetails, CartNote, CartOrder, CartSelectedAddon, CartSelectedAddonValue, CartSelectedOption, CartShippingInfo, CartSummaryTotals, CartTax, Catalog, CatalogHeader, type CatalogHeaderProps, CatalogPagination, type CatalogPartProps, CatalogProducts, type CatalogProductsProps, type CatalogProps, CatalogRoot, type CatalogRootProps, CatalogSummary, type CommerceContextValue, CommerceProvider, type CommerceProviderProps, CommerceStatus, CommerceStorefront, Connection, ConnectionEdge, DraftOrderContext, InventoryCount, LabelFilter, LineItemTotals, MediaObject, Money, OrderTotals, PageInfo, PriceRange, ProductCard, ProductCardAction, ProductCardDescription, ProductCardImage, type ProductCardPartProps, ProductCardPrice, type ProductCardProps, ProductCardRoot, type ProductCardRootProps, type ProductCardState, ProductCardTitle, ProductDetails, ProductDetailsAddToCart, ProductDetailsAvailability, ProductDetailsBackLink, ProductDetailsDescription, ProductDetailsGallery, ProductDetailsOption, type ProductDetailsOptionProps, type ProductDetailsOptionState, type ProductDetailsOptionValueState, ProductDetailsOptions, type ProductDetailsPartProps, ProductDetailsPrice, ProductDetailsPurchase, ProductDetailsPurchaseStatus, ProductDetailsQuantity, ProductDetailsRoot, type ProductDetailsRootProps, type ProductDetailsState, type ProductDetailsStatus, ProductDetailsTitle, ProductDetailsVariablesInput, ProductGridVariablesInput, SKU, SKUAttributeValue, SKUGroup, SKUGroupAttribute, SKUGroupAttributeValue, SKUGroupSKU, SKUPrice, SkuGroupResult, SkuGroupVariables, SkuGroupsResult, SkuGroupsVariables, SkuResult, SkuVariables, type StorefrontConfig, StorefrontProductAttribute, StorefrontProductAttributeValue, type StorefrontTheme, StringInFilter, addToCart, getAvailableInventoryQuantity, getCartSummaryTotals, getImageUrls, getLabeledSkuOptions, getPrimaryImageUrl, getProductAttributes, getProductName, getSingleMatchedSku, getSingleMatchedSkuId, money, useCommerce, useProductCard, useProductDetails, useProductDetailsOption };