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

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

package/test/components/CartSidebar/CartSidebar.browser.test.tsx

@@ -0,0 +1,209 @@
+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('next/dynamic', () => ({
+  default: (loader: () => Promise<unknown>) => {
+    const source = Function.prototype.toString.call(loader)
+    const chunk = /webpackChunkName:\s*"([^"]+)"/.exec(source)?.[1] ?? 'dynamic'
+
+    return function DynamicStub({
+      children,
+      ...props
+    }: React.PropsWithChildren<Record<string, unknown>>) {
+      const serializableProps = Object.fromEntries(
+        Object.entries(props).filter(
+          ([, value]) =>
+            value == null ||
+            typeof value === 'string' ||
+            typeof value === 'number' ||
+            typeof value === 'boolean'
+        )
+      )
+
+      return React.createElement(
+        'div',
+        {
+          'data-testid': chunk,
+          'data-props': JSON.stringify(serializableProps),
+        },
+        children
+      )
+    }
+  },
+}))
+
+const useUI = vi.hoisted(() => vi.fn())
+vi.mock('@faststore/ui', () => ({
+  Icon: ({ name }: { name?: string }) =>
+    React.createElement('span', { 'data-testid': 'icon', 'data-name': name }),
+  useFadeEffect: () => ({ fadeOut: vi.fn() }),
+  useUI,
+}))
+
+const useCart = vi.hoisted(() => vi.fn())
+vi.mock('src/sdk/cart', () => ({ useCart }))
+
+vi.mock('src/sdk/cart/useCheckoutButton', () => ({
+  useCheckoutButton: () => ({
+    onClick: vi.fn(),
+    disabled: false,
+    'data-testid': 'checkout-button',
+  }),
+}))
+
+vi.mock('src/sdk/session', () => ({
+  useSession: () => ({ currency: { code: 'USD' } }),
+}))
+
+vi.mock('@faststore/sdk', () => ({
+  sendAnalyticsEvent: vi.fn(),
+}))
+
+import CartSidebar from 'src/components/cart/CartSidebar'
+
+const CAMPAIGN_VRN = 'vrn:recommendations:acc:rec-cross-v2:campaign-1'
+
+const cartItem = {
+  id: 'item-1',
+  quantity: 1,
+  price: 100,
+  listPrice: 120,
+  itemOffered: {
+    sku: 'sku-1',
+    name: 'SKU 1',
+    gtin: 'gtin-1',
+    brand: { name: 'Brand' },
+    isVariantOf: { productGroupID: 'pg-1', name: 'Product 1' },
+  },
+}
+
+const sidebarProps = {
+  title: 'Your cart',
+  alert: {
+    icon: { icon: 'Truck', alt: 'Truck' },
+    text: 'Free shipping',
+  },
+  emptyCart: {
+    title: 'Your Cart is empty',
+    buttonLabel: 'Start Shopping',
+  },
+  checkoutButton: {
+    label: 'Checkout',
+    loadingLabel: 'Loading...',
+    icon: { icon: 'ArrowRight', alt: 'Arrow Right' },
+  },
+  quantitySelector: { useUnitMultiplier: false },
+}
+
+const enabledRecommendations = {
+  shouldDisplayRecommendationShelf: true,
+  campaignVrn: CAMPAIGN_VRN,
+  title: 'You may also like',
+}
+
+function filledCart() {
+  useCart.mockReturnValue({
+    items: [cartItem],
+    gifts: [],
+    totalItems: 1,
+    isValidating: false,
+    subTotal: 100,
+    total: 100,
+    subTotalWithTaxes: 110,
+    totalWithTaxes: 110,
+  })
+}
+
+function emptyCart() {
+  useCart.mockReturnValue({
+    items: [],
+    gifts: [],
+    totalItems: 0,
+    isValidating: false,
+    subTotal: 0,
+    total: 0,
+    subTotalWithTaxes: 0,
+    totalWithTaxes: 0,
+  })
+}
+
+beforeEach(() => {
+  useUI.mockReturnValue({ cart: true, closeCart: vi.fn() })
+  filledCart()
+})
+
+afterEach(() => {
+  vi.clearAllMocks()
+})
+
+describe('CartSidebar recommendation shelf gate', () => {
+  it('does not mount the shelf when the display toggle is off', () => {
+    const { queryByTestId } = render(
+      <CartSidebar
+        {...sidebarProps}
+        recommendations={{
+          shouldDisplayRecommendationShelf: false,
+          campaignVrn: CAMPAIGN_VRN,
+        }}
+      />
+    )
+
+    expect(queryByTestId('CartRecommendationShelf')).toBeNull()
+    expect(queryByTestId('OrderSummary')).toBeTruthy()
+  })
+
+  it('does not mount the shelf when the toggle is on but campaign VRN is missing', () => {
+    const { queryByTestId } = render(
+      <CartSidebar
+        {...sidebarProps}
+        recommendations={{ shouldDisplayRecommendationShelf: true }}
+      />
+    )
+
+    expect(queryByTestId('CartRecommendationShelf')).toBeNull()
+  })
+
+  it('does not mount the shelf on an empty cart, even with the toggle on', () => {
+    emptyCart()
+
+    const { queryByTestId } = render(
+      <CartSidebar {...sidebarProps} recommendations={enabledRecommendations} />
+    )
+
+    expect(queryByTestId('EmptyCart')).toBeTruthy()
+    expect(queryByTestId('CartRecommendationShelf')).toBeNull()
+    expect(queryByTestId('OrderSummary')).toBeNull()
+  })
+
+  it('renders the shelf before OrderSummary when the cart has items', () => {
+    const { getByTestId } = render(
+      <CartSidebar {...sidebarProps} recommendations={enabledRecommendations} />
+    )
+
+    const footerChildren = Array.from(
+      getByTestId('UICartSidebarFooter').children
+    )
+
+    expect(footerChildren[0]).toHaveAttribute(
+      'data-testid',
+      'CartRecommendationShelf'
+    )
+    expect(footerChildren[1]).toHaveAttribute('data-testid', 'OrderSummary')
+  })
+
+  it('omits shouldDisplayRecommendationShelf from the shelf props', () => {
+    const { getByTestId } = render(
+      <CartSidebar {...sidebarProps} recommendations={enabledRecommendations} />
+    )
+
+    const props = JSON.parse(
+      getByTestId('CartRecommendationShelf').getAttribute('data-props') ?? '{}'
+    ) as Record<string, unknown>
+
+    expect(props).not.toHaveProperty('shouldDisplayRecommendationShelf')
+    expect(props.campaignVrn).toBe(CAMPAIGN_VRN)
+    expect(props.title).toBe('You may also like')
+  })
+})

package/test/components/RecommendationShelf/RecommendationShelf.browser.test.tsx

@@ -75,6 +75,25 @@ afterEach(() => {
 })
 
 describe('RecommendationShelf', () => {
+  it('forwards extra props onto the root section', async () => {
+    useRecommendations.mockReturnValue({
+      data: recommendationData,
+      isLoading: false,
+      error: null,
+    })
+
+    const { getByTestId } = render(
+      <RecommendationShelf
+        campaignVrn={CAMPAIGN_VRN}
+        data-testid="recommendation-shelf"
+      />
+    )
+
+    await waitFor(() => {
+      expect(getByTestId('recommendation-shelf').tagName).toBe('SECTION')
+    })
+  })
+
   it('renders a product card per recommended product', async () => {
     useRecommendations.mockReturnValue({
       data: recommendationData,

package/test/sdk/recommendations/useRecommendationShelf.browser.test.tsx

@@ -151,7 +151,7 @@ describe('useRecommendationShelf', () => {
     })
   })
 
-  it('follows the live cart context when not frozen', () => {
+  it('follows the live cart context', () => {
     useCart.mockReturnValue({ items: [cartItem('pg-1')] })
 
     const { rerender } = renderHook(() =>