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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faststore/core",
-  "version": "4.7.1-dev.2",
+  "version": "4.8.0-dev.1",
   "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.2",
-    "@faststore/lighthouse": "4.7.1-dev.2",
-    "@faststore/ui": "4.7.1-dev.2",
-    "@faststore/diagnostics": "4.7.1-dev.2",
-    "@faststore/sdk": "4.7.1-dev.2"
+    "@faststore/api": "4.8.0-dev.1",
+    "@faststore/diagnostics": "4.8.0-dev.1",
+    "@faststore/lighthouse": "4.8.0-dev.1",
+    "@faststore/sdk": "4.8.0-dev.1",
+    "@faststore/ui": "4.8.0-dev.1"
   },
   "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}

package/src/components/sections/RecommendationShelf/README.md

@@ -6,14 +6,23 @@ CMS section that renders a carousel of personalized product recommendations from
 - **Registration:** global CMS component (`$componentKey: "RecommendationShelf"`), available on any page via CMS.
 - **Session opt-in:** personalization session starts via the `experimental.enableRecommendations` discovery feature flag (Layout, every page). When the flag is off, any mounted Recommendation Shelf starts the session as a fallback if `userId` is missing.
 
+Recommendations are rendered by two surfaces that share one data layer (`src/sdk/recommendations`):
+
+| Surface | Component | Configured in | Layout |
+| --- | --- | --- | --- |
+| Page shelf | `RecommendationShelf` | Its own CMS component | Full-width carousel |
+| Mini cart shelf | `CartRecommendationShelf` | The **Recommendations** group of the **Cart Sidebar** component | Compact carousel inside the cart drawer |
+
 ## Contents
 
 - [Prerequisites](#prerequisites)
 - [Setup](#setup)
 - [CMS configuration](#cms-configuration)
 - [Campaign types (VRN) and context](#campaign-types-vrn-and-context)
+- [Mini cart shelf](#mini-cart-shelf)
 - [Runtime behavior](#runtime-behavior)
 - [Code-level overrides](#code-level-overrides)
+- [CSS customization](#css-customization)
 - [Placement guidelines](#placement-guidelines)
 - [Privacy and cache](#privacy-and-cache)
 - [Troubleshooting](#troubleshooting)
@@ -99,24 +108,53 @@ The campaign type is derived from the `<campaign-type>` segment of the VRN:
 
 Context-based campaigns (cross-sell, similar items, visual similarity, next interaction) skip the request when no context products are available. Context-agnostic campaigns (top sellers, personalized, last seen, search-based) ignore `itemsContext`.
 
+## Mini cart shelf
+
+A compact shelf can be rendered **inside the cart drawer**, between the cart items and the order summary. It is the highest-intent cross-sell surface in the store: the shopper has just added an item and the drawer is open.
+
+The CMS cannot nest one section inside another, so this shelf is not a separate CMS component — it is configured as a **Recommendations** group on the **Cart Sidebar** component.
+
+Schema: `cms/faststore/components/cms_component__cartsidebar.jsonc`, under `recommendations`.
+
+| CMS property | Key | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- | --- |
+| Should display Recommendation Shelf? | `shouldDisplayRecommendationShelf` | boolean | No | `false` | Opt-in. Off means the drawer does not mount the shelf, so there is no request and nothing rendered. |
+| Campaign VRN | `campaignVrn` | string | No | — | Same VRN taxonomy and validation as the page shelf. Needed at runtime when the display toggle is on; the drawer does not fetch without it. |
+| Title | `title` | string | No | — | Overrides the shelf title. Falls back to the campaign title. |
+| › Items per page | `carouselConfiguration.itemsPerPage` | number | No | `1` | The drawer is around 340px wide on every breakpoint, so keep this low. Fractional values such as `1.5` hint that the carousel scrolls. |
+| › Carousel track variant | `carouselConfiguration.variant` | `slide` \| `scroll` | No | `scroll` | Carousel navigation mode. |
+| › Navigation controls | `carouselConfiguration.controls` | `complete` \| `navigationArrows` \| `paginationBullets` | No | `navigationArrows` | Visible navigation controls. |
+| › Show discount badge? | `productCardConfiguration.showDiscountBadge` | boolean | No | `true` | Shows the discount badge. |
+| › Cards should be bordered? | `productCardConfiguration.bordered` | boolean | No | `false` | Renders bordered cards. |
+
+Differences from the page shelf:
+
+- **The context is always the cart.** There is no `itemsContext` property.
+- **The context follows the live cart.** Adding a product updates the campaign context while the drawer stays open.
+- **Taxes are inherited.** The shelf reuses the drawer's own **Taxes Configuration** so recommended products and cart items price alike.
+- **It does not render on an empty cart.** The drawer shows the empty-cart state instead of mounting the shelf. Context-agnostic campaigns that would work without product context are still suppressed on this surface.
+- **It only fetches when the drawer opens.** The drawer is gated by `SECTIONS_OUT_OF_VIEWPORT`, and the shelf ships in its own chunk, so stores without a mini cart shelf download neither the component nor its styles.
+- **CSS hook.** The root also has `data-fs-cart-recommendation-shelf`, so store CSS can style the drawer shelf without hitting page shelves. See [CSS customization](#css-customization).
+
 ## Runtime behavior
 
 All recommendation work runs client-side after hydration:
 
-1. **Session start (feature flag + shelf fallback)** — `Layout` calls `useStartRecommendationSession()` once. The hook starts the session when `experimental.enableRecommendations` is `true` (no CMS lookup). When the flag is `false`, `useRecommendationShelf()` (used by every RecommendationShelf) calls the same hook as a fallback while `userId` is missing (`undefined` or `null`), in parallel with cookie retry. Cookie (`vtex-rec-user-start-session`) + in-memory lock ensure at most one attempt per browser session. If `userId` is already available, the shelf does not start the session.
+1. **Session start (feature flag + shelf fallback)** — `Layout` calls `useStartRecommendationSession()` once. The hook starts the session when `experimental.enableRecommendations` is `true` (no CMS lookup). When the flag is `false`, `useRecommendationShelf()` (used by every RecommendationShelf, including the mini cart) calls the same hook as a fallback while `userId` is missing (`undefined` or `null`), in parallel with cookie retry. Cookie (`vtex-rec-user-start-session`) + in-memory lock ensure at most one attempt per browser session. If `userId` is already available, the shelf does not start the session.
 2. **User id resolution** — `useRecommendationUserId()` reads the `vtex-rec-user-id` cookie, retrying until a value is available or the retry budget is exhausted.
 3. **Request arguments** — `getRecommendationArguments()` builds `{ userId, campaignVrn, products }` or returns `null` when the VRN is invalid, the user id is missing, or a context-based campaign has no context products.
 4. **Fetch** — `useRecommendations()` runs `ClientRecommendationsQuery` and returns `products`, `correlationId`, and `campaign`.
 5. **Render** — shows `ProductShelfSkeleton` while loading; returns `null` on error or empty results; otherwise renders the carousel and optional heading.
-6. **Tracking** — when correlation and campaign identifiers are present, the shelf emits `data-af-*` attributes for Activity Flow. PDP product views use `product:*` meta tags from `pages/[slug]/p.tsx`.
+6. **Tracking** — when correlation and campaign identifiers are present, the shelf emits `data-af-*` attributes for Activity Flow (`recommendation-shelf` on the root, `recommendation-shelf-product` on items). PDP product views use `product:*` meta tags from `pages/[slug]/p.tsx`.
 
-Steps 1 to 4 carry no presentation: they live in `src/sdk/recommendations` and are orchestrated by `useRecommendationShelf()`, which the shelf consumes.
+Steps 1 to 4 live in `src/sdk/recommendations` behind `useRecommendationShelf()`. Step 5 is owned by `RecommendationShelf`; the mini cart shelf is a thin wrapper around it that locks cart context and applies drawer-safe carousel/tax defaults — so `ProductCard` / `mapProductToProductCard` work the same way on both surfaces.
 
 Related files:
 
 - Shared data layer: `src/sdk/recommendations/`
-- Shelf: `src/components/sections/RecommendationShelf/`
-- Hook: `src/sdk/analytics/hooks/useStartRecommendationSession.ts`
+- Page shelf (also the presentation used by the mini cart): `src/components/sections/RecommendationShelf/`
+- Mini cart wrapper: `src/components/cart/CartRecommendationShelf/`
+- Session hook: `src/sdk/analytics/hooks/useStartRecommendationSession.ts`
 - Layout: `src/Layout.tsx`
 - Flag: `discovery.config.default.js` → `experimental.enableRecommendations`
 
@@ -143,7 +181,30 @@ import { RecommendationShelf } from 'src/components/sections/RecommendationShelf
 - **`ProductCard`**: custom card component (defaults to the core `ProductCard`).
 - **`mapProductToProductCard`**: maps each recommended product (normalized `StoreProduct`) into card props. When provided, it fully owns the card props and the default `productCardConfiguration` merge no longer applies.
 
-Campaign types and VRN validation are defined in `src/sdk/recommendations/vrn.ts` (`VRN_TYPE_TO_RECOMMENDATION`). Updates should be made there and mirrored in the CMS schema `pattern`.
+Campaign types and VRN validation are defined in `src/sdk/recommendations/vrn.ts` (`VRN_TYPE_TO_RECOMMENDATION`). Updates should be made there and mirrored in the `pattern` of both CMS schemas (`cms_component__recommendationshelf.jsonc` and the `recommendations` group of `cms_component__cartsidebar.jsonc`).
+
+The mini cart shelf (`CartRecommendationShelf`) reuses `RecommendationShelf`, so the same `ProductCard` / `mapProductToProductCard` overrides apply. By default it renders `CartRecommendationProductCard`, which adds an **Add to cart** action (first offer / SKU, drawer stays open). Because the drawer is rendered by `CartSidebar` from CMS props, passing a custom card from a store means customizing `CartSidebar` (or `CartRecommendationShelf`) under `src/customizations` and forwarding the override into `recommendations`.
+
+## CSS customization
+
+The shelf root (`<section>`) exposes `data-fs-*` attributes as styling hooks, so store CSS can target the shelf without depending on layout class names (`section-product-shelf`, `layout__section`, …):
+
+| Attribute | Present on | Purpose |
+| --- | --- | --- |
+| `data-fs-recommendation-shelf` | Every shelf (page and mini cart) | Root hook for the recommendation shelf. |
+| `data-fs-cart-recommendation-shelf` | Mini cart shelf only | Distinguishes the drawer instance from page shelves. |
+
+Related hooks on the same tree: `data-fs-recommendation-shelf-title` (heading) and `data-fs-recommendation-shelf-item` (each card wrapper).
+
+```scss
+[data-fs-recommendation-shelf] {
+  /* page shelf and mini cart shelf */
+}
+
+[data-fs-cart-recommendation-shelf] {
+  /* mini cart shelf only */
+}
+```
 
 ## Placement guidelines
 
@@ -153,6 +214,7 @@ As a global component, the shelf can be placed on any CMS page. Suggested placem
 - **PDP:** context-based campaigns with `itemsContext: PDP`.
 - **Cart:** cross-sell with `itemsContext: CART`.
 - **PLP:** context-agnostic campaigns.
+- **Cart drawer (mini cart):** cross-sell, configured on the **Cart Sidebar** component. See [Mini cart shelf](#mini-cart-shelf).
 
 Prefer enabling `experimental.enableRecommendations` so the session is ready on every page. Stores without the flag and without a Recommendation Shelf never call `startRecommendationSession`.
 
@@ -171,6 +233,12 @@ Prefer enabling `experimental.enableRecommendations` so the session is ready on
 3. For context-based campaigns, is product context available (`PDP` on a product page, or a non-empty cart for `CART`)?
 4. Did the campaign return products? An empty response renders nothing by design.
 
+**The mini cart shelf does not render.** Same checklist, plus:
+
+5. Is **Should display Recommendation Shelf?** enabled on the **Cart Sidebar** component (under **Recommendations**), not on a separate Recommendation Shelf? Only that shape opts the drawer in.
+6. With the discovery flag off, the session starts when the shelf mounts (when the drawer opens). Confirm `vtex-rec-user-start-session` and then `vtex-rec-user-id` after opening the cart.
+7. Is the cart empty? The mini cart shelf does not mount until there is at least one item. Use a page Recommendation Shelf for empty-cart campaigns.
+
 **Skeleton never resolves.** Inspect the console and the GraphQL `recommendations` response for pending or failing requests.
 
 **No tracking events.** Confirm that the Activity Flow script is present and that PDP `product:*` meta tags and shelf `data-af-*` attributes are rendered.

package/src/components/sections/RecommendationShelf/RecommendationShelf.tsx

@@ -16,16 +16,20 @@ import type {
 } from './RecommendationShelf.types'
 import styles from './section.module.scss'
 
+const DEFAULT_SECTION_CLASS_NAME = `${styles.section} section-product-shelf layout__section section`
+
 export function RecommendationShelf<
   TCardProps extends object = ProductCardProps,
 >({
   title,
   campaignVrn,
   itemsContext = 'PDP',
+  className,
   ProductCard,
   mapProductToProductCard,
   carouselConfiguration,
   productCardConfiguration,
+  ...otherProps
 }: RecommendationShelfProps<TCardProps>) {
   const {
     itemsPerPageDesktop = 4,
@@ -82,7 +86,8 @@ export function RecommendationShelf<
 
   return (
     <section
-      className={`${styles.section} section-product-shelf layout__section section`}
+      className={className ?? DEFAULT_SECTION_CLASS_NAME}
+      {...otherProps}
       {...(shouldAddAFAttr
         ? {
             'data-af-element': 'recommendation-shelf' as const,
@@ -93,10 +98,17 @@ export function RecommendationShelf<
             'data-af-products': productIds,
           }
         : {})}
+      data-fs-recommendation-shelf
     >
-      <ProductShelfSkeleton loading={isLoading} itemsPerPage={itemsPerPage}>
+      <ProductShelfSkeleton
+        loading={isLoading}
+        itemsPerPage={Math.ceil(itemsPerPage)}
+      >
         {(title || campaign?.title) && (
-          <h2 className="text__title-section layout__content">
+          <h2
+            className="text__title-section layout__content"
+            data-fs-recommendation-shelf-title
+          >
             {title || campaign?.title}
           </h2>
         )}