@faststore/core 4.5.0-dev.0 → 4.5.0-dev.1

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

@@ -0,0 +1,223 @@
+import { type ComponentType, useId, useMemo } from 'react'
+
+import { usePDP } from '@faststore/core'
+import { ProductShelf, Carousel } from '@faststore/ui'
+import type { ProductSummary_ProductFragment } from '@generated/graphql'
+
+import storeConfig from 'discovery.config'
+
+import DefaultProductCard, {
+  type ProductCardProps,
+} from 'src/components/product/ProductCard'
+import ProductShelfSkeleton from 'src/components/skeletons/ProductShelfSkeleton'
+import { useCart } from 'src/sdk/cart'
+import useScreenResize from 'src/sdk/ui/useScreenResize'
+
+import type {
+  RecommendationProductCardMapper,
+  RecommendationShelfProps,
+} from './RecommendationShelf.types'
+import styles from './section.module.scss'
+import {
+  useRecommendations,
+  type RecommendationInput,
+} from './useRecommendations'
+import { useRecommendationUserId } from './useRecommendationUserId'
+import { getTypeFromVrn } from './vrn'
+
+function getRecommendationArguments(
+  campaignVrn: string,
+  context: { userId?: string | null; contextProducts: string[] }
+): RecommendationInput | null {
+  const { userId, contextProducts } = context
+  const type = getTypeFromVrn(campaignVrn)
+
+  // `type` is null for malformed/unknown VRNs; bail out so we never fetch (and
+  // never throw) on an invalid campaign coming from the CMS.
+  if (!type || !userId) return null
+
+  switch (type) {
+    case 'NEXT_INTERACTION':
+    case 'VISUAL_SIMILARITY':
+    case 'CROSS_SELL':
+    case 'SIMILAR_ITEMS':
+      // These campaigns need product context. Without any (e.g. `CART` context
+      // on an empty cart, or `PDP` context outside a product page), skip the
+      // fetch instead of requesting recommendations we can't anchor.
+      if (contextProducts.length === 0) {
+        return null
+      }
+      return {
+        userId,
+        campaignVrn,
+        products: contextProducts,
+      }
+    default:
+      return {
+        userId,
+        campaignVrn,
+        products: [],
+      }
+  }
+}
+
+export function RecommendationShelf<
+  TCardProps extends object = ProductCardProps,
+>({
+  title,
+  campaignVrn,
+  itemsContext = 'PDP',
+  ProductCard,
+  mapProductToProductCard,
+  carouselConfiguration,
+  productCardConfiguration,
+}: RecommendationShelfProps<TCardProps>) {
+  const {
+    itemsPerPageDesktop = 4,
+    itemsPerPageMobile = 2,
+    variant = 'scroll',
+    infiniteMode = false,
+    controls,
+  } = carouselConfiguration ?? {}
+
+  const CardComponent = (ProductCard ??
+    DefaultProductCard) as ComponentType<TCardProps>
+
+  const mapToCardProps = (mapProductToProductCard ??
+    ((product: ProductSummary_ProductFragment, index: number) => ({
+      product,
+      index,
+      ...productCardConfiguration,
+    }))) as RecommendationProductCardMapper<TCardProps>
+
+  const id = useId()
+  const { isMobile, isTablet } = useScreenResize()
+  // Treat mobile and tablet viewports (<= 768px) as "mobile" for paging, which
+  // matches the carousel layout the shelf was designed around.
+  const itemsPerPage =
+    isMobile || isTablet ? itemsPerPageMobile : itemsPerPageDesktop
+
+  const userId = useRecommendationUserId(campaignVrn)
+
+  const { data: productDetailPage } = usePDP()
+  const { items: cartItems } = useCart()
+
+  // Resolve the products used as context for the request from the configured
+  // source: the current PDP product, or the (deduplicated) cart items.
+  const contextProducts = useMemo(() => {
+    if (itemsContext === 'CART') {
+      return Array.from(
+        new Set(
+          cartItems
+            .map((item) => item.itemOffered.isVariantOf.productGroupID)
+            .filter(Boolean)
+        )
+      )
+    }
+
+    const pdpProduct = productDetailPage?.product?.isVariantOf?.productGroupID
+
+    return pdpProduct ? [pdpProduct] : []
+  }, [itemsContext, cartItems, productDetailPage])
+
+  // Gate the whole feature behind the opt-in flag: when Recommendations is
+  // disabled the shelf never requests recommendations (nor renders).
+  const recommendationArgs = storeConfig.experimental.enableRecommendations
+    ? getRecommendationArguments(campaignVrn, {
+        userId,
+        contextProducts,
+      })
+    : null
+
+  const { data, isLoading, error } = useRecommendations(recommendationArgs)
+
+  const items = data?.products || []
+  const correlationId = data?.correlationId
+  const campaignId = data?.campaign.id
+
+  const productIds = useMemo(
+    () => items.map((p) => p.isVariantOf.productGroupID).join(', '),
+    [items]
+  )
+
+  const shouldAddAFAttr = !!(
+    !isLoading &&
+    correlationId &&
+    campaignId &&
+    productIds.length
+  )
+
+  if (error) {
+    // Don't log `recommendationArgs`: it carries the userId. Log only
+    // non-identifying context.
+    console.error(
+      'Error fetching recommendations',
+      error.cause,
+      error.message,
+      'for campaign',
+      campaignVrn
+    )
+    return null
+  }
+
+  if (!isLoading && items.length === 0) {
+    return null
+  }
+
+  return (
+    <section
+      className={`${styles.section} section-product-shelf layout__section section`}
+      {...(shouldAddAFAttr
+        ? {
+            'data-af-element': 'recommendation-shelf' as const,
+            'data-af-onimpression': true,
+            'data-af-onview': true,
+            'data-af-correlation-id': correlationId,
+            'data-af-campaign-id': campaignId,
+            'data-af-products': productIds,
+          }
+        : {})}
+    >
+      <ProductShelfSkeleton loading={isLoading} itemsPerPage={itemsPerPage}>
+        {(title || data?.campaign.title) && (
+          <h2 className="text__title-section layout__content">
+            {title || data?.campaign.title}
+          </h2>
+        )}
+
+        <ProductShelf>
+          <Carousel
+            id={id}
+            itemsPerPage={itemsPerPage}
+            variant={variant}
+            infiniteMode={infiniteMode}
+            controls={controls}
+          >
+            {items.map((item, index) => {
+              const productId = item.isVariantOf.productGroupID
+
+              return (
+                <div
+                  key={item.id}
+                  data-fs-recommendation-shelf-item
+                  {...(shouldAddAFAttr
+                    ? {
+                        'data-af-element': 'recommendation-shelf-product',
+                        'data-af-correlation-id': correlationId,
+                        'data-af-campaign-id': campaignId,
+                        'data-af-product-id': productId,
+                        'data-af-onclick': !!productId,
+                        'data-af-product-position': index + 1,
+                      }
+                    : {})}
+                >
+                  <CardComponent {...mapToCardProps(item, index)} />
+                </div>
+              )
+            })}
+          </Carousel>
+        </ProductShelf>
+      </ProductShelfSkeleton>
+    </section>
+  )
+}

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

@@ -0,0 +1,111 @@
+import type { ComponentType } from 'react'
+
+import type { CarouselProps } from '@faststore/ui'
+import type { ProductSummary_ProductFragment } from '@generated/graphql'
+
+import type { ProductCardProps } from 'src/components/product/ProductCard'
+
+/**
+ * Maps a recommendation product (a normalized `StoreProduct`, identical to the
+ * search response consumed by the rest of the shelves) into the props passed to
+ * the card component. Defaults to identity (`(product, index) => ({ product,
+ * index })`). Override it — typically together with `ProductCard` — to render
+ * custom cards that read additional/personalized fields.
+ */
+export type RecommendationProductCardMapper<TCardProps = ProductCardProps> = (
+  product: ProductSummary_ProductFragment,
+  index: number
+) => TCardProps
+
+/**
+ * Source of the products used as context for the recommendation request:
+ * - `'PDP'`: the current product detail page product.
+ * - `'CART'`: the products currently in the cart (useful for cross-sell on the
+ *   cart page).
+ */
+export type ItemContext = 'PDP' | 'CART'
+
+export type RecommendationShelfProps<
+  TCardProps extends object = ProductCardProps,
+> = {
+  readonly title?: string
+  readonly campaignVrn: string
+  /**
+   * Where to read the products used as context for the recommendation request:
+   * - `'PDP'`: the current product detail page product.
+   * - `'CART'`: the products currently in the cart (useful for cross-sell on the
+   *   cart page).
+   *
+   * Only affects campaigns that require product context (cross-sell, similar
+   * items, visual similarity, next interaction). Context-agnostic campaigns
+   * (top items, personalized, last seen, search-based) ignore it.
+   * @default 'PDP'
+   */
+  readonly itemsContext?: ItemContext
+  /**
+   * Custom card component rendered for each recommended product. Defaults to the
+   * core `ProductCard`. This is a code-level override and is not exposed through
+   * the CMS schema (`cms_component__RecommendationShelf.jsonc`).
+   */
+  readonly ProductCard?: ComponentType<TCardProps>
+  /**
+   * Maps a recommendation product into the props of the card component. Defaults
+   * to passing the product through as `{ product, index, ...productCardConfiguration }`.
+   * When provided, this mapper is fully responsible for the card props (the
+   * default `productCardConfiguration` merge no longer applies). This is a
+   * code-level override and is not exposed through the CMS schema.
+   */
+  readonly mapProductToProductCard?: RecommendationProductCardMapper<TCardProps>
+  /**
+   * Carousel behaviour and paging configuration. Forwarded to the underlying
+   * `Carousel`.
+   */
+  readonly carouselConfiguration?: {
+    /**
+     * Number of items per page on desktop viewports. Forwarded to the
+     * underlying `Carousel` as `itemsPerPage` when the viewport is desktop.
+     * @default 4
+     */
+    readonly itemsPerPageDesktop?: number
+    /**
+     * Number of items per page on mobile and tablet viewports. Forwarded to the
+     * underlying `Carousel` as `itemsPerPage` when the viewport is mobile/tablet.
+     * @default 2
+     */
+    readonly itemsPerPageMobile?: number
+    /**
+     * How the carousel navigates between items. Forwarded to the underlying
+     * `Carousel`.
+     * @default 'scroll'
+     */
+    readonly variant?: CarouselProps['variant']
+    /**
+     * Enables infinite navigation (only applies to the `slide` variant).
+     * Forwarded to the underlying `Carousel`.
+     * @default false
+     */
+    readonly infiniteMode?: CarouselProps['infiniteMode']
+    /**
+     * Which navigation elements are visible. Forwarded to the underlying
+     * `Carousel`.
+     */
+    readonly controls?: CarouselProps['controls']
+  }
+  /**
+   * Forwarded to each `ProductCard` rendered by the shelf.
+   */
+  readonly productCardConfiguration?: {
+    readonly showDiscountBadge?: boolean
+    readonly bordered?: boolean
+  }
+}
+
+export type RecommendationType =
+  | 'CROSS_SELL'
+  | 'SIMILAR_ITEMS'
+  | 'PERSONALIZED'
+  | 'TOP_ITEMS'
+  | 'LAST_SEEN'
+  | 'SEARCH_BASED'
+  | 'VISUAL_SIMILARITY'
+  | 'NEXT_INTERACTION'

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

@@ -0,0 +1 @@
+export * from './RecommendationShelf'

package/src/components/sections/RecommendationShelf/section.module.scss

@@ -0,0 +1,49 @@
+@use "@faststore/ui/src/styles/base/utilities";
+@use "sass:meta";
+
+@layer components {
+  .section {
+    [data-fs-recommendation-shelf-item] {
+      display: flex;
+      width: 100%;
+      height: 100%;
+
+      > * {
+        width: 100%;
+      }
+    }
+
+    [data-fs-product-shelf-skeleton] {
+      --fs-carousel-item-margin-right: var(--fs-spacing-3);
+
+      padding-bottom: var(--fs-spacing-5);
+
+      [data-fs-product-shelf-items] {
+        @include utilities.layout-content;
+      }
+
+      @include utilities.media("<tablet") {
+        [data-fs-product-shelf-item] {
+          &:not(:last-of-type) {
+            margin-right: var(--fs-carousel-item-margin-right);
+          }
+        }
+      }
+    }
+
+    @include meta.load-css("~@faststore/ui/src/components/atoms/Badge/styles");
+    @include meta.load-css("~@faststore/ui/src/components/atoms/Button/styles");
+    @include meta.load-css("~@faststore/ui/src/components/atoms/Icon/styles");
+    @include meta.load-css("~@faststore/ui/src/components/atoms/Link/styles");
+    @include meta.load-css("~@faststore/ui/src/components/atoms/Price/styles");
+    @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/molecules/ProductPrice/styles");
+    @include meta.load-css("~@faststore/ui/src/components/organisms/ProductShelf/styles");
+  }
+}

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

@@ -0,0 +1,49 @@
+import { useEffect, useState } from 'react'
+
+import { getUserIdFromCookie } from 'src/sdk/analytics/utils'
+import { retry } from 'src/utils/retry'
+
+/**
+ * Reads the anonymous recommendation user id from the cookie set by the
+ * personalization pixel.
+ *
+ * The pixel may take a while to load and set the cookie, so the lookup is
+ * retried until a value is available (or the budget runs out). The returned
+ * value is tri-state:
+ *
+ * - `undefined`: still resolving (initial state);
+ * - `null`: lookup finished without a usable id (e.g. the pixel never set it);
+ * - `string`: the resolved user id.
+ */
+export function useRecommendationUserId(
+  campaignVrn: string
+): string | null | undefined {
+  const [userId, setUserId] = useState<string | null | undefined>(undefined)
+
+  useEffect(() => {
+    const controller = new AbortController()
+
+    retry(() => getUserIdFromCookie(), { signal: controller.signal })
+      .then((value) => {
+        if (!controller.signal.aborted) {
+          setUserId(value || null)
+        }
+      })
+      .catch((retryError) => {
+        console.error(
+          'Error retrieving userId from cookie',
+          retryError,
+          campaignVrn
+        )
+        if (!controller.signal.aborted) {
+          setUserId(null)
+        }
+      })
+
+    return () => {
+      controller.abort()
+    }
+  }, [campaignVrn])
+
+  return userId
+}

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

@@ -0,0 +1,55 @@
+import { gql } from '@faststore/core/api'
+import type { ClientRecommendationsQueryQuery } from '@generated/graphql'
+import { useQuery } from 'src/sdk/graphql/useQuery'
+
+// Recommendations return the same normalized `StoreProduct` shape as the search
+// response, so the shelf renders identical product cards to regular shelves.
+// We select `...ProductSummary_product` (the fragment consumed by `ProductCard`)
+// to keep this interface consistent with the rest of the components.
+const query = gql(`query ClientRecommendationsQuery(
+  $campaignVrn: String!
+  $userId: String
+  $products: [String!]
+) {
+  recommendations(
+    userId: $userId
+    campaignVrn: $campaignVrn
+    products: $products
+  ) {
+    products {
+      ...ProductSummary_product
+    }
+    correlationId
+    campaign {
+      id
+      title
+      type
+    }
+  }
+}
+`)
+
+export type RecommendationInput = {
+  userId: string
+  campaignVrn: string
+  products: string[]
+}
+
+export type RecommendationResponse =
+  ClientRecommendationsQueryQuery['recommendations']
+export type RecommendationProduct = RecommendationResponse['products'][number]
+
+export const useRecommendations = (args: RecommendationInput | null) => {
+  const { data, isLoading, error } = useQuery<
+    ClientRecommendationsQueryQuery,
+    RecommendationInput
+  >(query, args ?? ({} as RecommendationInput), {
+    doNotRun: args === null,
+  })
+
+  return {
+    data: data?.recommendations,
+    error,
+    isLoading,
+  }
+}

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

@@ -0,0 +1,55 @@
+import type { RecommendationType } from './RecommendationShelf.types'
+
+// Single source of truth for the campaign taxonomy: maps each Intelligent Search
+// campaign VRN type to its `RecommendationType`. The supported VRN types, the
+// validation regex and the VRN-to-type resolution are all derived from this map
+// so the list of campaign types lives in exactly one place.
+//
+// Reference:
+//   Cross-Sell          rec-cross-v2
+//   Similar Items       rec-similar-v2
+//   Personalized        rec-persona-v2
+//   Last Seen           rec-last-v2
+//   Top Sellers         rec-top-items-v2
+//   Search-Based        rec-search-v2
+//   Next Interactions   rec-next-v2
+//   Visual Similarity   rec-visual-v2
+const VRN_TYPE_TO_RECOMMENDATION = {
+  'rec-cross-v2': 'CROSS_SELL',
+  'rec-similar-v2': 'SIMILAR_ITEMS',
+  'rec-persona-v2': 'PERSONALIZED',
+  'rec-last-v2': 'LAST_SEEN',
+  'rec-top-items-v2': 'TOP_ITEMS',
+  'rec-search-v2': 'SEARCH_BASED',
+  'rec-next-v2': 'NEXT_INTERACTION',
+  'rec-visual-v2': 'VISUAL_SIMILARITY',
+} as const satisfies Record<string, RecommendationType>
+
+type RecommendationVrnType = keyof typeof VRN_TYPE_TO_RECOMMENDATION
+
+const vrnPattern = new RegExp(
+  `^vrn:recommendations:[^:]+:(${Object.keys(VRN_TYPE_TO_RECOMMENDATION).join(
+    '|'
+  )}):[^:]+$`
+)
+
+export function isValidVrn(campaignVrn: string): boolean {
+  return vrnPattern.test(campaignVrn)
+}
+
+function parseCampaignVrn(campaignVrn: string) {
+  const [, , accountName, campaignType, campaignId] = campaignVrn.split(':')
+
+  return { accountName, campaignType, campaignId }
+}
+
+// Resolves a campaign VRN into its `RecommendationType`. Returns `null` for
+// malformed or unknown VRNs so callers can degrade gracefully instead of
+// throwing during render.
+export function getTypeFromVrn(campaignVrn: string): RecommendationType | null {
+  const { campaignType } = parseCampaignVrn(campaignVrn)
+
+  return (
+    VRN_TYPE_TO_RECOMMENDATION[campaignType as RecommendationVrnType] ?? null
+  )
+}

package/src/pages/[slug]/p.tsx

@@ -69,6 +69,14 @@ const COMPONENTS: Record<string, ComponentType<any>> = {
   ...CUSTOM_COMPONENTS,
 }
 
+// Maps schema.org `itemCondition` URLs to the values accepted by the
+// Open Graph `product:condition` meta tag (`new` | `refurbished` | `used`).
+const OG_PRODUCT_CONDITION_BY_SCHEMA: Record<string, string> = {
+  'https://schema.org/NewCondition': 'new',
+  'https://schema.org/RefurbishedCondition': 'refurbished',
+  'https://schema.org/UsedCondition': 'used',
+}
+
 type Props = PDPContentType & {
   data: ServerProductQueryQuery
   globalSections: GlobalSectionsData
@@ -123,6 +131,11 @@ function Page({
       .toString()
   }
 
+  const productCondition =
+    OG_PRODUCT_CONDITION_BY_SCHEMA[
+      product.offers.offers[0]?.itemCondition ?? ''
+    ]
+
   let itemListElements = product.breadcrumbList.itemListElement ?? []
   if (itemListElements.length !== 0) {
     itemListElements = itemListElements.map(
@@ -199,6 +212,38 @@ function Page({
             property: 'product:price:currency',
             content: currency.code,
           },
+          {
+            property: 'product:id',
+            content: product.isVariantOf?.productGroupID ?? undefined,
+          },
+          {
+            property: 'product:sku',
+            content: product.sku,
+          },
+          {
+            property: 'product:name',
+            content: product.name,
+          },
+          {
+            property: 'product:category',
+            content: itemListElements[0]?.name ?? undefined,
+          },
+          {
+            property: 'product:url',
+            content: meta.canonical,
+          },
+          {
+            property: 'product:brand',
+            content: product.brand.name,
+          },
+          ...(productCondition
+            ? [
+                {
+                  property: 'product:condition',
+                  content: productCondition,
+                },
+              ]
+            : []),
         ]}
         titleTemplate={titleTemplate}
       />