@faststore/core 4.7.1-dev.1 → 4.8.0-dev.0

package/cms/faststore/sections.json

@@ -2985,6 +2985,84 @@
               "default": "Tax included"
             }
           }
+        },
+        "recommendations": {
+          "title": "Recommendations",
+          "description": "Optional shelf of personalized product recommendations rendered inside the cart drawer, between the cart items and the order summary.",
+          "type": "object",
+          "properties": {
+            "shouldDisplayRecommendationShelf": {
+              "title": "Should display Recommendation Shelf?",
+              "description": "When enabled, fetches recommendations when the shopper opens the cart. Off by default so stores that do not use Recommendations never hit the Recommendations API. The personalization session starts via experimental.enableRecommendations, or as a fallback when this shelf mounts.",
+              "type": "boolean",
+              "default": false
+            },
+            "title": {
+              "title": "Title",
+              "description": "Override the shelf title. If not set, the campaign title will be used.",
+              "type": "string"
+            },
+            "campaignVrn": {
+              "title": "Campaign VRN",
+              "description": "Recommendation campaign VRN (e.g. vrn:recommendations:my-account:rec-cross-v2:abc123). The mini cart shelf only mounts when the cart has items, so it never fetches or renders on an empty cart — including context-agnostic campaigns (top sellers, personalized, last seen, search-based). Use a page Recommendation Shelf for empty-cart campaigns.",
+              "type": "string",
+              "pattern": "^vrn:recommendations:[^:]+:(rec-cross-v2|rec-similar-v2|rec-persona-v2|rec-last-v2|rec-top-items-v2|rec-search-v2|rec-next-v2|rec-visual-v2):[^:]+$"
+            },
+            "carouselConfiguration": {
+              "title": "Carousel Configuration",
+              "type": "object",
+              "properties": {
+                "itemsPerPage": {
+                  "title": "Items per page",
+                  "description": "Number of products visible at once. Fractional values such as 1.5 hint that the carousel scrolls.",
+                  "type": "number",
+                  "default": 1
+                },
+                "variant": {
+                  "title": "Carousel track variant",
+                  "description": "How the carousel navigates between items.",
+                  "type": "string",
+                  "default": "scroll",
+                  "enum": ["slide", "scroll"],
+                  "enumNames": ["Slide", "Scroll"]
+                },
+                "infiniteMode": {
+                  "title": "Infinite navigation?",
+                  "description": "Only applies to the 'slide' variant.",
+                  "type": "boolean",
+                  "default": false
+                },
+                "controls": {
+                  "title": "Navigation controls",
+                  "description": "Which navigation elements should be visible.",
+                  "type": "string",
+                  "default": "navigationArrows",
+                  "enum": ["complete", "navigationArrows", "paginationBullets"],
+                  "enumNames": [
+                    "Arrows and bullets",
+                    "Arrows only",
+                    "Bullets only"
+                  ]
+                }
+              }
+            },
+            "productCardConfiguration": {
+              "title": "Product Card Configuration",
+              "type": "object",
+              "properties": {
+                "showDiscountBadge": {
+                  "title": "Show discount badge?",
+                  "type": "boolean",
+                  "default": true
+                },
+                "bordered": {
+                  "title": "Cards should be bordered?",
+                  "type": "boolean",
+                  "default": false
+                }
+              }
+            }
+          }
         }
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faststore/core",
-  "version": "4.7.1-dev.1",
+  "version": "4.8.0-dev.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -71,11 +71,11 @@
     "style-loader": "^3.3.1",
     "swr": "^2.2.5",
     "use-sync-external-store": "^1.6.0",
-    "@faststore/api": "4.7.1-dev.1",
-    "@faststore/diagnostics": "4.7.1-dev.1",
-    "@faststore/ui": "4.7.1-dev.1",
-    "@faststore/sdk": "4.7.1-dev.1",
-    "@faststore/lighthouse": "4.7.1-dev.1"
+    "@faststore/api": "4.8.0-dev.0",
+    "@faststore/lighthouse": "4.8.0-dev.0",
+    "@faststore/sdk": "4.8.0-dev.0",
+    "@faststore/ui": "4.8.0-dev.0",
+    "@faststore/diagnostics": "4.8.0-dev.0"
   },
   "devDependencies": {
     "@cypress/code-coverage": "^3.12.1",

package/src/components/cart/CartRecommendationShelf/CartRecommendationProductCard.tsx

@@ -0,0 +1,88 @@
+import type { MouseEventHandler } from 'react'
+
+import ProductCard, {
+  type ProductCardProps,
+} from 'src/components/product/ProductCard'
+import { useBuyButton } from 'src/sdk/cart/useBuyButton'
+
+export interface CartRecommendationProductCardProps extends ProductCardProps {}
+
+/**
+ * Product card used by the cart drawer recommendation shelf. Same surface as
+ * the page shelf card, plus an add-to-cart action that appends the recommended
+ * SKU without reopening the drawer (`shouldOpenCart: false`).
+ *
+ * Adds the first offer returned by the recommendations API (the card already
+ * represents a specific `StoreProduct` / SKU). Multi-SKU matrix selection is
+ * out of scope here — shoppers who need another variant can open the PDP.
+ */
+function CartRecommendationProductCard({
+  product,
+  buttonLabel = 'Add to cart',
+  onButtonClick,
+  ...otherProps
+}: Readonly<CartRecommendationProductCardProps>) {
+  const {
+    id,
+    sku,
+    gtin,
+    brand,
+    isVariantOf,
+    isVariantOf: { name },
+    unitMultiplier,
+    image: [img],
+    offers: {
+      offers: [
+        {
+          listPrice,
+          price,
+          listPriceWithTaxes,
+          seller,
+          priceWithTaxes,
+          priceToken,
+        },
+      ],
+    },
+    additionalProperty,
+  } = product
+
+  const buyProps = useBuyButton(
+    {
+      id,
+      price,
+      priceWithTaxes,
+      listPrice,
+      listPriceWithTaxes,
+      seller,
+      quantity: 1,
+      priceToken,
+      itemOffered: {
+        sku,
+        name,
+        gtin,
+        image: [img],
+        brand,
+        isVariantOf,
+        additionalProperty,
+        unitMultiplier,
+      },
+    },
+    false
+  )
+
+  const handleClick: MouseEventHandler<HTMLButtonElement> = (event) => {
+    buyProps.onClick(event)
+    onButtonClick?.(event)
+  }
+
+  return (
+    <ProductCard
+      {...otherProps}
+      product={product}
+      buttonLabel={buttonLabel}
+      onButtonClick={handleClick}
+    />
+  )
+}
+
+export default CartRecommendationProductCard

package/src/components/cart/CartRecommendationShelf/CartRecommendationShelf.tsx

@@ -0,0 +1,110 @@
+import type { CarouselProps } from '@faststore/ui'
+import type { ProductSummary_ProductFragment } from '@generated/graphql'
+
+import type { ProductCardProps } from 'src/components/product/ProductCard'
+import {
+  RecommendationShelf,
+  type RecommendationProductCardMapper,
+  type RecommendationShelfProps,
+} from 'src/components/sections/RecommendationShelf'
+
+import CartRecommendationProductCard from './CartRecommendationProductCard'
+import styles from './section.module.scss'
+
+export type CartRecommendationShelfProps<
+  TCardProps extends object = ProductCardProps,
+> = Omit<
+  RecommendationShelfProps<TCardProps>,
+  'itemsContext' | 'className' | 'carouselConfiguration'
+> & {
+  /**
+   * Drawer-safe carousel configuration. Mapped onto
+   * `RecommendationShelf`'s desktop/mobile paging props (the drawer is the
+   * same width on every breakpoint, so both viewports share this count).
+   */
+  readonly carouselConfiguration?: {
+    /**
+     * Products visible at once. Fractional values (e.g. `1.5`) hint that the
+     * carousel scrolls.
+     * @default 1
+     */
+    readonly itemsPerPage?: number
+    /** @default 'scroll' */
+    readonly variant?: CarouselProps['variant']
+    /** @default false */
+    readonly infiniteMode?: CarouselProps['infiniteMode']
+    /** @default 'navigationArrows' */
+    readonly controls?: CarouselProps['controls']
+  }
+  /**
+   * Forwarded from the cart drawer so recommended products display prices under
+   * the same tax rules as the cart items next to them. Applied through the
+   * default `mapProductToProductCard`; a custom mapper is responsible for
+   * forwarding it itself.
+   */
+  readonly taxesConfiguration?: ProductCardProps['taxesConfiguration']
+}
+
+/**
+ * Compact recommendation shelf for the cart drawer.
+ *
+ * Presentation is owned by `RecommendationShelf` so code-level overrides
+ * (`ProductCard`, `mapProductToProductCard`, …) work the same way as on the
+ * page shelf. This wrapper only locks cart-specific behaviour: cart context,
+ * drawer-safe carousel defaults, tax/image sizing for the narrow panel, and the
+ * default `CartRecommendationProductCard` (add-to-cart without reopening the
+ * drawer).
+ */
+function CartRecommendationShelf<TCardProps extends object = ProductCardProps>({
+  title,
+  campaignVrn,
+  carouselConfiguration,
+  productCardConfiguration,
+  taxesConfiguration,
+  ProductCard,
+  mapProductToProductCard,
+}: CartRecommendationShelfProps<TCardProps>) {
+  const {
+    itemsPerPage = 1,
+    variant = 'scroll',
+    infiniteMode = false,
+    controls = 'navigationArrows',
+  } = carouselConfiguration ?? {}
+
+  const mapToCardProps: RecommendationProductCardMapper<TCardProps> =
+    mapProductToProductCard ??
+    ((product: ProductSummary_ProductFragment, index: number) =>
+      ({
+        product,
+        index,
+        bordered: productCardConfiguration?.bordered ?? false,
+        showDiscountBadge: productCardConfiguration?.showDiscountBadge ?? true,
+        taxesConfiguration,
+        imgProps: { sizes: '(max-width: 768px) 45vw, 15vw' },
+      }) as TCardProps)
+
+  return (
+    <RecommendationShelf<TCardProps>
+      title={title}
+      campaignVrn={campaignVrn}
+      itemsContext="CART"
+      className={styles.section}
+      ProductCard={
+        (ProductCard ??
+          CartRecommendationProductCard) as RecommendationShelfProps<TCardProps>['ProductCard']
+      }
+      mapProductToProductCard={mapToCardProps}
+      productCardConfiguration={productCardConfiguration}
+      carouselConfiguration={{
+        itemsPerPageDesktop: itemsPerPage,
+        itemsPerPageMobile: itemsPerPage,
+        variant,
+        infiniteMode,
+        controls,
+      }}
+      data-fs-cart-recommendation-shelf
+    />
+  )
+}
+
+export default CartRecommendationShelf

package/src/components/cart/CartRecommendationShelf/index.ts

@@ -0,0 +1,4 @@
+export { default } from './CartRecommendationShelf'
+export type { CartRecommendationShelfProps } from './CartRecommendationShelf'
+export { default as CartRecommendationProductCard } from './CartRecommendationProductCard'
+export type { CartRecommendationProductCardProps } from './CartRecommendationProductCard'

package/src/components/cart/CartRecommendationShelf/section.module.scss

@@ -0,0 +1,124 @@
+@use "sass:meta";
+
+@layer components {
+  // Rendered as a direct child of `[data-fs-cart-sidebar]`, which is a flex
+  // column whose footer is sticky. The shelf therefore takes its natural height
+  // and never pushes the checkout button out of reach.
+  // Passed to `RecommendationShelf` as `className`, so page-section utilities
+  // (`section-product-shelf`, `layout__section`, …) are not applied.
+  .section {
+    --fs-product-shelf-items-padding-top: 0;
+    --fs-product-shelf-items-padding-bottom: var(--fs-spacing-1);
+    --fs-carousel-item-margin-right: var(--fs-spacing-2);
+
+    padding: var(--fs-spacing-2) 0;
+    border-top: var(--fs-border-width) solid var(--fs-border-color-light);
+
+    [data-fs-recommendation-shelf-title] {
+      padding: 0 var(--fs-spacing-3) var(--fs-spacing-2);
+      margin: 0;
+      font-size: var(--fs-text-size-2);
+      font-weight: var(--fs-text-weight-semibold);
+      color: var(--fs-color-text);
+    }
+
+    [data-fs-carousel],
+    [data-fs-product-shelf-skeleton] {
+      padding: 0 var(--fs-spacing-3);
+    }
+
+    [data-fs-recommendation-shelf-item] {
+      display: flex;
+      width: 100%;
+      height: 100%;
+
+      > * {
+        width: 100%;
+      }
+    }
+
+    // The drawer is ~340px wide on every breakpoint, so two cards land under
+    // the card's default 10rem min-width and would overflow the track. Let the
+    // card follow the carousel item width and scale its type down with it.
+    [data-fs-product-card] {
+      --fs-product-card-min-width: 0;
+      --fs-product-card-gap: var(--fs-spacing-1);
+      --fs-product-card-padding: var(--fs-spacing-1);
+      --fs-product-card-title-size: var(--fs-text-size-1);
+      --fs-product-card-price-size: var(--fs-text-size-1);
+      --fs-product-card-title-max-lines: 2;
+    }
+
+    // Full-width add-to-cart so the action stays tappable on ~half-drawer cards.
+    [data-fs-product-card-actions] {
+      width: 100%;
+
+      [data-fs-button] {
+        --fs-button-height: var(--fs-spacing-6);
+        --fs-button-text-size: var(--fs-text-size-1);
+        --fs-button-padding: var(--fs-spacing-0) var(--fs-spacing-1);
+        --fs-button-gap: var(--fs-spacing-1);
+
+        width: 100%;
+      }
+    }
+
+    // Button, Icon, Badge, Link, Price and ProductPrice already load in
+    // CartSidebar; this chunk only adds styles the drawer does not have.
+    @include meta.load-css("~@faststore/ui/src/components/atoms/SROnly/styles");
+    @include meta.load-css("~@faststore/ui/src/components/atoms/Skeleton/styles");
+    @include meta.load-css("~@faststore/ui/src/components/molecules/Carousel/styles");
+    @include meta.load-css("~@faststore/ui/src/components/molecules/DiscountBadge/styles");
+    @include meta.load-css("~@faststore/ui/src/components/molecules/Rating/styles");
+    @include meta.load-css("~@faststore/ui/src/components/molecules/ProductCard/styles");
+    @include meta.load-css("~@faststore/ui/src/components/molecules/ProductCardSkeleton/styles");
+    @include meta.load-css("~@faststore/ui/src/components/organisms/ProductShelf/styles");
+
+    // Keep the product fully visible: `cover` plus a height cap was clipping
+    // photos on both the wide drawer and the narrow one. A square box with
+    // `contain` stays compact without cropping.
+    [data-fs-product-card] [data-fs-product-card-image],
+    [data-fs-product-card-skeleton-image] {
+      width: min(100%, 7.5rem);
+      aspect-ratio: 1;
+      margin-inline: auto;
+      background-color: var(--fs-color-neutral-1);
+
+      img {
+        object-fit: contain;
+      }
+    }
+
+    [data-fs-product-card-skeleton] {
+      --fs-product-card-skeleton-sectioned-min-width: 0;
+      --fs-product-card-skeleton-padding: var(--fs-spacing-1);
+    }
+
+    // The drawer (and `[data-fs-product-shelf-items]`) clips overflow, so
+    // arrows must stay inside the padded carousel — not offset outside it.
+    [data-fs-product-shelf-items] {
+      overflow: visible;
+    }
+
+    [data-fs-carousel] {
+      overflow: visible;
+
+      [data-fs-carousel-track] {
+        padding: 0;
+      }
+
+      [data-fs-carousel-controls] {
+        width: 100%;
+        pointer-events: auto;
+        opacity: 1;
+
+        [data-fs-button] {
+          --fs-button-height: var(--fs-spacing-6);
+
+          width: var(--fs-button-height);
+          min-width: var(--fs-button-height);
+        }
+      }
+    }
+  }
+}

package/src/components/cart/CartSidebar/CartSidebar.tsx

@@ -8,6 +8,7 @@ import type {
 import type { CurrencyCode, ViewCartEvent } from '@faststore/sdk'
 import { Icon, useFadeEffect, useUI } from '@faststore/ui'
 import { type ReactNode, useCallback, useEffect, useMemo } from 'react'
+import type { CartRecommendationShelfProps } from '../CartRecommendationShelf'
 import { useCart } from 'src/sdk/cart'
 import { useCheckoutButton } from 'src/sdk/cart/useCheckoutButton'
 import { useSession } from 'src/sdk/session'
@@ -58,6 +59,15 @@ const OrderSummary = dynamic(
   () => import(/* webpackChunkName: "OrderSummary" */ '../OrderSummary'),
   { ssr: false }
 )
+// Kept in its own chunk so stores without a mini cart shelf never download the
+// shelf or the product card/carousel styles it pulls in.
+const CartRecommendationShelf = dynamic(
+  () =>
+    import(
+      /* webpackChunkName: "CartRecommendationShelf" */ '../CartRecommendationShelf'
+    ),
+  { ssr: false }
+)
 
 import styles from './section.module.scss'
 
@@ -127,6 +137,20 @@ export interface CartSidebarProps {
     usePriceWithTaxes?: boolean
     taxesLabel?: string
   }
+  /**
+   * Optional recommendation shelf rendered inside the drawer. Off by default
+   * (`shouldDisplayRecommendationShelf: false`) so the drawer stays as it was:
+   * no personalization session, no request, nothing rendered.
+   *
+   * Taxes are not configured here — the shelf reuses the drawer's own
+   * `taxesConfiguration` so recommended products and cart items price alike.
+   * `ProductCard` / `mapProductToProductCard` are code-level overrides (same
+   * contract as the page `RecommendationShelf`) and are omitted from the CMS
+   * schema; store customizations can still pass them when wrapping this section.
+   */
+  recommendations?: Omit<CartRecommendationShelfProps, 'taxesConfiguration'> & {
+    shouldDisplayRecommendationShelf?: boolean
+  }
 }
 
 function CartSidebar({
@@ -143,7 +167,8 @@ function CartSidebar({
   },
   quantitySelector,
   taxesConfiguration,
-}: CartSidebarProps) {
+  recommendations,
+}: Readonly<CartSidebarProps>) {
   const btnProps = useCheckoutButton()
   const {
     items,
@@ -161,6 +186,26 @@ function CartSidebar({
 
   const isEmpty = useMemo(() => items.length === 0, [items])
 
+  // The mini cart shelf does not mount until the cart has at least one item,
+  // so empty carts never fetch — including context-agnostic campaigns. The
+  // element is only inserted in the non-empty footer below.
+  let recommendationShelf: ReactNode = null
+
+  if (
+    recommendations?.shouldDisplayRecommendationShelf &&
+    recommendations.campaignVrn
+  ) {
+    const { shouldDisplayRecommendationShelf: _, ...recommendationShelfProps } =
+      recommendations
+
+    recommendationShelf = (
+      <CartRecommendationShelf
+        {...recommendationShelfProps}
+        taxesConfiguration={taxesConfiguration}
+      />
+    )
+  }
+
   useEffect(() => {
     if (!displayCart) {
       return
@@ -214,6 +259,7 @@ function CartSidebar({
               </UICartSidebarList>
 
               <UICartSidebarFooter>
+                {recommendationShelf}
                 <OrderSummary
                   subTotal={
                     taxesConfiguration?.usePriceWithTaxes

package/src/components/product/ProductCard/ProductCard.tsx

@@ -4,7 +4,7 @@ import {
   ProductCardImage as UIProductCardImage,
   ProductComparisonTrigger as UIProductComparisonTrigger,
 } from '@faststore/ui'
-import { memo, useMemo } from 'react'
+import { memo, useMemo, type MouseEventHandler } from 'react'
 
 import { gql } from '@generated'
 import type { ProductSummary_ProductFragment } from '@generated/graphql'
@@ -42,9 +42,10 @@ export interface ProductCardProps {
    */
   ratingValue?: number
   /**
-   * Callback function when button is clicked.
+   * Callback function when the card action button is clicked. When set, the
+   * button is rendered (unless the product is out of stock).
    */
-  onButtonClick?: () => void
+  onButtonClick?: MouseEventHandler<HTMLButtonElement>
   /**
    * Specifies the button's label.
    */
@@ -178,6 +179,7 @@ function ProductCard({
           }}
           ratingValue={ratingValue}
           outOfStock={outOfStock}
+          buttonLabel={buttonLabel}
           onButtonClick={onButtonClick}
           linkProps={linkProps}
           showDiscountBadge={hasDiscount && showDiscountBadge}