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

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>
         )}

package/src/components/sections/RecommendationShelf/RecommendationShelf.types.ts

@@ -1,4 +1,4 @@
-import type { ComponentType } from 'react'
+import type { ComponentPropsWithoutRef, ComponentType } from 'react'
 
 import type { CarouselProps } from '@faststore/ui'
 import type { ProductSummary_ProductFragment } from '@generated/graphql'
@@ -22,7 +22,7 @@ export type RecommendationProductCardMapper<TCardProps = ProductCardProps> = (
 
 export type RecommendationShelfProps<
   TCardProps extends object = ProductCardProps,
-> = {
+> = Omit<ComponentPropsWithoutRef<'section'>, 'children' | 'title'> & {
   readonly title?: string
   readonly campaignVrn: string
   /**
@@ -37,6 +37,12 @@ export type RecommendationShelfProps<
    * @default 'PDP'
    */
   readonly itemsContext?: ItemContext
+  /**
+   * Replaces the default page-section class list. Surfaces like the cart drawer
+   * pass their own module class so the shelf does not pick up full-page layout
+   * utilities (`section-product-shelf`, `layout__section`, …).
+   */
+  readonly className?: string
   /**
    * Custom card component rendered for each recommended product. Defaults to the
    * core `ProductCard`. This is a code-level override and is not exposed through

package/src/components/sections/RecommendationShelf/index.ts

@@ -1 +1,7 @@
-export * from './RecommendationShelf'
+export { RecommendationShelf } from './RecommendationShelf'
+export type {
+  ItemContext,
+  RecommendationProductCardMapper,
+  RecommendationShelfProps,
+  RecommendationType,
+} from './RecommendationShelf.types'

package/src/sdk/recommendations/useRecommendationShelf.ts

@@ -72,8 +72,8 @@ const EMPTY_ITEMS: RecommendationResponse['products'] = []
  * Headless data layer behind every recommendation shelf: resolves the campaign
  * type, the anonymous user id and the product context, then fetches the
  * campaign. It renders nothing — presentation lives in the shelf components
- * that consume it, so a new surface can reuse the campaign rules instead of
- * reimplementing them.
+ * that consume it, so a page-wide carousel and the compact cart drawer shelf
+ * share exactly one implementation of the campaign rules.
  *
  * When `userId` is missing (`undefined` or `null`), starts the personalization
  * session as a fallback in parallel with cookie retry (Layout already starts

package/test/components/CartRecommendationShelf/CartRecommendationProductCard.browser.test.tsx

@@ -0,0 +1,125 @@
+import '@testing-library/jest-dom/vitest'
+import { fireEvent, render } from '@testing-library/react'
+import React from 'react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const buyOnClick = vi.hoisted(() => vi.fn())
+const useBuyButtonMock = vi.hoisted(() => vi.fn())
+
+vi.mock('src/sdk/cart/useBuyButton', () => ({
+  useBuyButton: (...args: unknown[]) => {
+    useBuyButtonMock(...args)
+    return {
+      onClick: buyOnClick,
+      'data-testid': 'buy-button',
+    }
+  },
+}))
+
+const productCardProps = vi.hoisted(() => vi.fn())
+vi.mock('src/components/product/ProductCard', () => ({
+  default: (props: Record<string, unknown>) => {
+    productCardProps(props)
+    return React.createElement(
+      'button',
+      {
+        type: 'button',
+        'data-testid': 'product-card',
+        onClick: props.onButtonClick as React.MouseEventHandler,
+      },
+      String(props.buttonLabel ?? '')
+    )
+  },
+}))
+
+import CartRecommendationProductCard from 'src/components/cart/CartRecommendationShelf/CartRecommendationProductCard'
+
+const product = {
+  id: 'p-1',
+  sku: 'sku-1',
+  gtin: 'gtin-1',
+  brand: { name: 'Brand' },
+  unitMultiplier: 1,
+  additionalProperty: [],
+  isVariantOf: {
+    productGroupID: 'pg-1',
+    name: 'Camera',
+  },
+  image: [{ url: 'https://example.com/cam.jpg', alternateName: 'Camera' }],
+  offers: {
+    lowPrice: 100,
+    lowPriceWithTaxes: 110,
+    offers: [
+      {
+        availability: 'https://schema.org/InStock',
+        listPrice: 120,
+        listPriceWithTaxes: 130,
+        price: 100,
+        priceWithTaxes: 110,
+        seller: { identifier: '1' },
+        priceToken: 'token',
+        quantity: 1,
+      },
+    ],
+  },
+}
+
+beforeEach(() => {
+  buyOnClick.mockClear()
+  useBuyButtonMock.mockClear()
+  productCardProps.mockClear()
+})
+
+afterEach(() => {
+  vi.clearAllMocks()
+})
+
+describe('CartRecommendationProductCard', () => {
+  it('wires useBuyButton with the recommended SKU and keeps the drawer closed', () => {
+    render(
+      <CartRecommendationProductCard product={product as never} index={0} />
+    )
+
+    expect(useBuyButtonMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        id: 'p-1',
+        quantity: 1,
+        price: 100,
+        itemOffered: expect.objectContaining({
+          sku: 'sku-1',
+          name: 'Camera',
+        }),
+      }),
+      false
+    )
+  })
+
+  it('renders an add-to-cart action and forwards clicks to useBuyButton', () => {
+    const { getByTestId, getByText } = render(
+      <CartRecommendationProductCard product={product as never} index={0} />
+    )
+
+    expect(productCardProps).toHaveBeenCalledWith(
+      expect.objectContaining({
+        buttonLabel: 'Add to cart',
+        onButtonClick: expect.any(Function),
+      })
+    )
+    expect(getByText('Add to cart')).toBeTruthy()
+
+    fireEvent.click(getByTestId('product-card'))
+    expect(buyOnClick).toHaveBeenCalledTimes(1)
+  })
+
+  it('allows overriding the button label', () => {
+    const { getByText } = render(
+      <CartRecommendationProductCard
+        product={product as never}
+        index={0}
+        buttonLabel="Add"
+      />
+    )
+
+    expect(getByText('Add')).toBeTruthy()
+  })
+})

package/test/components/CartRecommendationShelf/CartRecommendationShelf.browser.test.tsx

@@ -0,0 +1,286 @@
+import '@testing-library/jest-dom/vitest'
+import { render } from '@testing-library/react'
+import React from 'react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+vi.mock('@faststore/ui', () => {
+  const passthrough = ({ children }: React.PropsWithChildren) =>
+    React.createElement(React.Fragment, null, children)
+  return { ProductShelf: passthrough, Carousel: passthrough }
+})
+
+const productCardProps = vi.hoisted(() => vi.fn())
+vi.mock('src/components/product/ProductCard', () => ({
+  default: (props: Record<string, unknown>) => {
+    productCardProps(props)
+    return React.createElement('div', { 'data-testid': 'product-card' })
+  },
+}))
+
+vi.mock('src/components/skeletons/ProductShelfSkeleton', () => ({
+  default: ({
+    children,
+    loading,
+    itemsPerPage,
+  }: React.PropsWithChildren<{ loading?: boolean; itemsPerPage?: number }>) =>
+    React.createElement(
+      'div',
+      {
+        'data-testid': 'skeleton',
+        'data-loading': String(!!loading),
+        'data-items-per-page': String(itemsPerPage),
+      },
+      children
+    ),
+}))
+
+const useRecommendationShelf = vi.hoisted(() => vi.fn())
+vi.mock('src/sdk/recommendations', () => ({ useRecommendationShelf }))
+
+vi.mock('src/sdk/cart/useBuyButton', () => ({
+  useBuyButton: () => ({
+    onClick: vi.fn(),
+    'data-testid': 'buy-button',
+  }),
+}))
+
+vi.mock('src/sdk/ui/useScreenResize', () => ({
+  default: () => ({
+    isMobile: false,
+    isTablet: false,
+    isDesktop: true,
+    loading: false,
+  }),
+}))
+
+import CartRecommendationShelf from 'src/components/cart/CartRecommendationShelf'
+
+const CAMPAIGN_VRN = 'vrn:recommendations:acc:rec-cross-v2:campaign-1'
+
+const recommendationProduct = (id: string, productGroupID: string) => ({
+  id,
+  sku: `sku-${id}`,
+  gtin: `gtin-${id}`,
+  brand: { name: 'Brand' },
+  unitMultiplier: 1,
+  additionalProperty: [],
+  isVariantOf: { productGroupID, name: `Product ${id}` },
+  image: [{ url: `https://example.com/${id}.jpg`, alternateName: id }],
+  offers: {
+    lowPrice: 100,
+    lowPriceWithTaxes: 110,
+    offers: [
+      {
+        availability: 'https://schema.org/InStock',
+        listPrice: 120,
+        listPriceWithTaxes: 130,
+        price: 100,
+        priceWithTaxes: 110,
+        seller: { identifier: '1' },
+        priceToken: 'token',
+        quantity: 1,
+      },
+    ],
+  },
+})
+
+const result = (overrides: Record<string, unknown> = {}) => ({
+  items: [
+    recommendationProduct('p-1', 'pg-1'),
+    recommendationProduct('p-2', 'pg-2'),
+  ],
+  isLoading: false,
+  error: null,
+  campaign: { id: 'camp-1', title: 'You may also like', type: 'CROSS_SELL' },
+  correlationId: 'corr-1',
+  ...overrides,
+})
+
+beforeEach(() => {
+  useRecommendationShelf.mockReturnValue(result())
+})
+
+afterEach(() => {
+  vi.clearAllMocks()
+})
+
+describe('CartRecommendationShelf', () => {
+  it('delegates to RecommendationShelf with cart context', () => {
+    render(<CartRecommendationShelf campaignVrn={CAMPAIGN_VRN} />)
+
+    expect(useRecommendationShelf).toHaveBeenCalledWith({
+      campaignVrn: CAMPAIGN_VRN,
+      itemsContext: 'CART',
+    })
+  })
+
+  it('renders a card per recommended product under the campaign title', () => {
+    const { getAllByTestId, getByText } = render(
+      <CartRecommendationShelf campaignVrn={CAMPAIGN_VRN} />
+    )
+
+    expect(getAllByTestId('product-card')).toHaveLength(2)
+    expect(getByText('You may also like')).toBeTruthy()
+  })
+
+  it('prefers the configured title over the campaign title', () => {
+    const { getByText, queryByText } = render(
+      <CartRecommendationShelf
+        campaignVrn={CAMPAIGN_VRN}
+        title="Complete your purchase"
+      />
+    )
+
+    expect(getByText('Complete your purchase')).toBeTruthy()
+    expect(queryByText('You may also like')).toBeNull()
+  })
+
+  it('renders nothing when the campaign returns no products', () => {
+    useRecommendationShelf.mockReturnValue(result({ items: [] }))
+
+    const { container } = render(
+      <CartRecommendationShelf campaignVrn={CAMPAIGN_VRN} />
+    )
+
+    expect(container).toBeEmptyDOMElement()
+  })
+
+  it('renders nothing when the request fails, leaving the cart untouched', () => {
+    useRecommendationShelf.mockReturnValue(
+      result({ items: [], error: new Error('boom') })
+    )
+
+    const { container } = render(
+      <CartRecommendationShelf campaignVrn={CAMPAIGN_VRN} />
+    )
+
+    expect(container).toBeEmptyDOMElement()
+  })
+
+  it('shows the skeleton while loading', () => {
+    useRecommendationShelf.mockReturnValue(
+      result({ items: [], isLoading: true })
+    )
+
+    const { getByTestId } = render(
+      <CartRecommendationShelf campaignVrn={CAMPAIGN_VRN} />
+    )
+
+    expect(getByTestId('skeleton').getAttribute('data-loading')).toBe('true')
+  })
+
+  it('rounds a fractional items per page up for the skeleton', () => {
+    useRecommendationShelf.mockReturnValue(
+      result({ items: [], isLoading: true })
+    )
+
+    const { getByTestId } = render(
+      <CartRecommendationShelf
+        campaignVrn={CAMPAIGN_VRN}
+        carouselConfiguration={{ itemsPerPage: 1.5 }}
+      />
+    )
+
+    expect(getByTestId('skeleton').getAttribute('data-items-per-page')).toBe(
+      '2'
+    )
+  })
+
+  it('tags the shelf root so the cart drawer can target it', () => {
+    const { container } = render(
+      <CartRecommendationShelf campaignVrn={CAMPAIGN_VRN} />
+    )
+
+    const shelf = container.querySelector('[data-fs-recommendation-shelf]')
+    expect(shelf).toBeTruthy()
+    expect(shelf?.hasAttribute('data-fs-cart-recommendation-shelf')).toBe(true)
+  })
+
+  it('tags impressions with Activity Flow attributes', () => {
+    const { container } = render(
+      <CartRecommendationShelf campaignVrn={CAMPAIGN_VRN} />
+    )
+
+    const shelf = container.querySelector(
+      '[data-af-element="recommendation-shelf"]'
+    )
+    expect(shelf).toBeTruthy()
+    expect(shelf?.getAttribute('data-af-campaign-id')).toBe('camp-1')
+    expect(shelf?.getAttribute('data-af-products')).toBe('pg-1, pg-2')
+
+    const firstItem = container.querySelector(
+      '[data-fs-recommendation-shelf-item]'
+    )
+    expect(firstItem?.getAttribute('data-af-element')).toBe(
+      'recommendation-shelf-product'
+    )
+    expect(firstItem?.getAttribute('data-af-product-position')).toBe('1')
+  })
+
+  it('forwards the drawer taxes configuration to every card', () => {
+    const taxesConfiguration = {
+      usePriceWithTaxes: true,
+      taxesLabel: 'Tax included',
+    }
+
+    render(
+      <CartRecommendationShelf
+        campaignVrn={CAMPAIGN_VRN}
+        taxesConfiguration={taxesConfiguration}
+      />
+    )
+
+    expect(productCardProps).toHaveBeenCalledWith(
+      expect.objectContaining({ taxesConfiguration })
+    )
+  })
+
+  it('renders unbordered cards by default and honours the override', () => {
+    render(<CartRecommendationShelf campaignVrn={CAMPAIGN_VRN} />)
+
+    expect(productCardProps).toHaveBeenCalledWith(
+      expect.objectContaining({ bordered: false })
+    )
+
+    productCardProps.mockClear()
+
+    render(
+      <CartRecommendationShelf
+        campaignVrn={CAMPAIGN_VRN}
+        productCardConfiguration={{ bordered: true }}
+      />
+    )
+
+    expect(productCardProps).toHaveBeenCalledWith(
+      expect.objectContaining({ bordered: true })
+    )
+  })
+
+  it('uses CartRecommendationProductCard by default so cards expose add-to-cart', () => {
+    render(<CartRecommendationShelf campaignVrn={CAMPAIGN_VRN} />)
+
+    expect(productCardProps).toHaveBeenCalledWith(
+      expect.objectContaining({
+        buttonLabel: 'Add to cart',
+        onButtonClick: expect.any(Function),
+      })
+    )
+  })
+
+  it('forwards a custom ProductCard to RecommendationShelf', () => {
+    const CustomCard = (props: Record<string, unknown>) => {
+      productCardProps(props)
+      return React.createElement('div', { 'data-testid': 'custom-card' })
+    }
+
+    const { getAllByTestId, queryByTestId } = render(
+      <CartRecommendationShelf
+        campaignVrn={CAMPAIGN_VRN}
+        ProductCard={CustomCard}
+      />
+    )
+
+    expect(getAllByTestId('custom-card')).toHaveLength(2)
+    expect(queryByTestId('product-card')).toBeNull()
+  })
+})