Merge pull request #2072 from SalesforceCommerceCloud/feature/shopper-context

Merge `feature/shopper-context` into `v5/template-retail-react-app` branch

Author: bfeister

packages/template-retail-react-app/CHANGELOG.md

@@ -1,3 +1,13 @@
+## v5.0.0 (TBD)
+
+### New Features
+- Implement ability to set Shopper Context via search parameters in the Retail React App [#1986](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/1986)
+- Display a promo banner from Page Designer in the PLP page of the Retail React App [#2016](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2016)
+
+### Performance Improvements
+
+- PLP: When products are being refetched, only the pricing and promotions sections will display a skeleton in the ProductTile [#2064](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2064)
+
 ## v4.1.0-dev (Aug 8, 2024)
 
 - [Server Affinity] - Attach dwsid to SCAPI request headers & remove OCAPI proxy [#2090](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2090)

packages/template-retail-react-app/app/components/_app/index.jsx

@@ -53,6 +53,7 @@ import {AddToCartModalProvider} from '@salesforce/retail-react-app/app/hooks/use
 import useMultiSite from '@salesforce/retail-react-app/app/hooks/use-multi-site'
 import {useCurrentCustomer} from '@salesforce/retail-react-app/app/hooks/use-current-customer'
 import {useCurrentBasket} from '@salesforce/retail-react-app/app/hooks/use-current-basket'
+import {useUpdateShopperContext} from '@salesforce/retail-react-app/app/hooks/use-update-shopper-context'
 
 // HOCs
 import {withCommerceSdkReact} from '@salesforce/retail-react-app/app/components/with-commerce-sdk-react/with-commerce-sdk-react'
@@ -133,7 +134,6 @@ const App = (props) => {
 
     const [isOnline, setIsOnline] = useState(true)
     const styles = useStyleConfig('App')
-
     const {isOpen, onOpen, onClose} = useDisclosure()
     const {
         isOpen: isOpenStoreLocator,
@@ -228,6 +228,9 @@ const App = (props) => {
         })
     }, [])
 
+    // Handle updating the shopper context
+    useUpdateShopperContext()
+
     useEffect(() => {
         // Lets automatically close the mobile navigation when the
         // location path is changed.

packages/template-retail-react-app/app/components/_app/index.test.js

@@ -19,6 +19,9 @@ import mockConfig from '@salesforce/retail-react-app/config/mocks/default'
 import * as constants from '@salesforce/retail-react-app/app/constants'
 
 jest.mock('../../hooks/use-multi-site', () => jest.fn())
+jest.mock('../../hooks/use-update-shopper-context', () => ({
+    useUpdateShopperContext: jest.fn()
+}))
 
 let windowSpy
 let originalValue

packages/template-retail-react-app/app/components/product-tile/index.jsx

@@ -51,6 +51,15 @@ import {PRODUCT_BADGE_DETAILS} from '@salesforce/retail-react-app/app/constants'
 const IconButtonWithRegistration = withRegistration(IconButton)
 
 // Component Skeleton
+const PricingAndPromotionsSkeleton = () => {
+    return (
+        <Stack spacing={2} data-testid="sf-product-tile-pricing-and-promotions-skeleton">
+            <ChakraSkeleton width="80px" height="20px" />
+            <ChakraSkeleton width={{base: '120px', md: '220px'}} height="12px" />
+        </Stack>
+    )
+}
+
 export const Skeleton = () => {
     const styles = useMultiStyleConfig('ProductTile')
     return (
@@ -61,8 +70,7 @@ export const Skeleton = () => {
                         <ChakraSkeleton />
                     </AspectRatio>
                 </Box>
-                <ChakraSkeleton width="80px" height="20px" />
-                <ChakraSkeleton width={{base: '120px', md: '220px'}} height="12px" />
+                <PricingAndPromotionsSkeleton />
             </Stack>
         </Box>
     )
@@ -83,6 +91,7 @@ const ProductTile = (props) => {
         product,
         selectableAttributeId = PRODUCT_TILE_SELECTABLE_ATTRIBUTE_ID,
         badgeDetails = PRODUCT_BADGE_DETAILS,
+        isRefreshingData = false,
         ...rest
     } = props
     const {imageGroups, productId, representedProduct, variants} = product
@@ -245,12 +254,18 @@ const ProductTile = (props) => {
                 {/* Title */}
                 <Text {...styles.title}>{localizedProductName}</Text>
 
-                {/* Price */}
-                <DisplayPrice priceData={priceData} currency={currency} />
+                {isRefreshingData ? (
+                    <PricingAndPromotionsSkeleton />
+                ) : (
+                    <>
+                        {/* Price */}
+                        <DisplayPrice priceData={priceData} currency={currency} />
 
-                {/* Promotion call-out message */}
-                {shouldShowPromoCallout(productWithFilteredVariants) && (
-                    <PromoCallout product={productWithFilteredVariants} />
+                        {/* Promotion call-out message */}
+                        {shouldShowPromoCallout(productWithFilteredVariants) && (
+                            <PromoCallout product={productWithFilteredVariants} />
+                        )}
+                    </>
                 )}
             </Link>
             {enableFavourite && (
@@ -376,7 +391,11 @@ ProductTile.propTypes = {
     /**
      * Details of badge labels and the corresponding product custom properties that enable badges.
      */
-    badgeDetails: PropTypes.array
+    badgeDetails: PropTypes.array,
+    /**
+     * Determines whether to display a skeleton over personalizable data (e.g., pricing and promotions) during data refresh.
+     */
+    isRefreshingData: PropTypes.bool
 }
 
 export default ProductTile

packages/template-retail-react-app/app/components/product-tile/index.test.js

@@ -45,6 +45,17 @@ test('Renders Skeleton', () => {
     expect(skeleton).toBeDefined()
 })
 
+test('Renders PricingAndPromotionsSkeleton when isRefetching is true', async () => {
+    const {getAllByTestId, queryByTestId} = renderWithProviders(
+        <ProductTile isRefreshingData={true} product={mockMasterProductHitWithMultipleVariants} />
+    )
+
+    const skeleton = getAllByTestId('sf-product-tile-pricing-and-promotions-skeleton')
+
+    expect(skeleton).toBeDefined()
+    expect(queryByTestId('sf-product-tile-skeleton')).not.toBeInTheDocument()
+})
+
 test('Remove from wishlist cannot be muti-clicked', () => {
     const onClick = jest.fn()
 

packages/template-retail-react-app/app/constants.js

@@ -201,3 +201,33 @@ export const STORE_LOCATOR_DISTANCE = 100
 export const STORE_LOCATOR_NUM_STORES_PER_LOAD = 10
 export const STORE_LOCATOR_DISTANCE_UNIT = 'km'
 export const STORE_LOCATOR_IS_ENABLED = true
+
+// Constants for shopper context
+// Supported non-string field types used in SHOPPER_CONTEXT_SEARCH_PARAMS below.
+// Only non-string types need to be identified using the "type" field.
+// If no "type" field is present, the value will be parsed as a string by default.
+export const SHOPPER_CONTEXT_FIELD_TYPES = {
+    INT: 'int',
+    DOUBLE: 'double',
+    ARRAY: 'array'
+}
+export const SHOPPER_CONTEXT_SEARCH_PARAMS = {
+    sourceCode: {paramName: 'sourceCode'},
+    geoLocation: {
+        city: {paramName: 'city'},
+        country: {paramName: 'country'},
+        countryCode: {paramName: 'countryCode'},
+        latitude: {paramName: 'latitude', type: SHOPPER_CONTEXT_FIELD_TYPES.DOUBLE},
+        longitude: {paramName: 'longitude', type: SHOPPER_CONTEXT_FIELD_TYPES.DOUBLE},
+        metroCode: {paramName: 'metroCode'},
+        postalCode: {paramName: 'postalCode'},
+        region: {paramName: 'region'},
+        regionCode: {paramName: 'regionCode'}
+    },
+    customQualifiers: {
+        // Add custom qualifiers here
+    },
+    assignmentQualifiers: {
+        // Add assignment qualifiers here
+    }
+}

packages/template-retail-react-app/app/hooks/use-shopper-context-search-params.js

@@ -0,0 +1,98 @@
+/*
+ * Copyright (c) 2024, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: BSD-3-Clause
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+
+import {useMemo} from 'react'
+import {useLocation} from 'react-router-dom'
+
+// Constants
+import {
+    SHOPPER_CONTEXT_SEARCH_PARAMS,
+    SHOPPER_CONTEXT_FIELD_TYPES
+} from '@salesforce/retail-react-app/app/constants'
+
+/**
+ * This hook will return a shopper context object when search params related
+ * to shopper context are present.
+ *
+ * @returns {Object} A shopper context object that can be passed to the Shopper Context API
+ */
+export const useShopperContextSearchParams = () => {
+    const {search} = useLocation()
+    return useMemo(() => {
+        const searchParamsObj = new URLSearchParams(search)
+        const {
+            geoLocation: geoLocationSearchParams,
+            customQualifiers: customQualiferSearchParams,
+            assignmentQualifiers: assignmentQualifierSearchParams,
+            ...rootQualifierSearchParams
+        } = SHOPPER_CONTEXT_SEARCH_PARAMS
+
+        const rootQualifiers = getShopperContextFromSearchParams(
+            searchParamsObj,
+            rootQualifierSearchParams
+        )
+        const geoLocation = getShopperContextFromSearchParams(
+            searchParamsObj,
+            geoLocationSearchParams
+        )
+        const customQualifiers = getShopperContextFromSearchParams(
+            searchParamsObj,
+            customQualiferSearchParams
+        )
+        const assignmentQualifiers = getShopperContextFromSearchParams(
+            searchParamsObj,
+            assignmentQualifierSearchParams
+        )
+
+        return {
+            ...rootQualifiers,
+            ...(Object.keys(geoLocation).length && {geoLocation}),
+            ...(Object.keys(customQualifiers).length && {customQualifiers}),
+            ...(Object.keys(assignmentQualifiers).length && {assignmentQualifiers})
+        }
+    }, [search])
+}
+
+/**
+ * Converts search parameters into a shopper context object based on a provided mapping.
+ *
+ * @private
+ * @param {URLSearchParams} searchParamsObj - The search parameters object
+ * @param {Object} searchParamToApiFieldMapping - An object mapping search parameter keys to API field names and types
+ * @returns {Object} The shopper context object where keys are API field names and values are the converted search parameter values.
+ */
+export const getShopperContextFromSearchParams = (
+    searchParamsObj,
+    searchParamToApiFieldMapping
+) => {
+    const shopperContextObj = {}
+    for (const [searchParamKey, searchParamValue] of searchParamsObj.entries()) {
+        // Find the mapping entry where paramName matches the searchParamKey
+        const mappingEntry = Object.entries(searchParamToApiFieldMapping).find(
+            ([, entry]) => entry.paramName === searchParamKey
+        )
+
+        if (mappingEntry) {
+            const [apiFieldName, {type}] = mappingEntry
+            switch (type) {
+                case SHOPPER_CONTEXT_FIELD_TYPES.INT:
+                case SHOPPER_CONTEXT_FIELD_TYPES.DOUBLE:
+                    shopperContextObj[apiFieldName] = Number(searchParamValue)
+                    break
+                case SHOPPER_CONTEXT_FIELD_TYPES.ARRAY:
+                    shopperContextObj[apiFieldName] = searchParamsObj.getAll(searchParamKey)
+                    break
+                default:
+                    // Default to string
+                    shopperContextObj[apiFieldName] = searchParamValue
+                    break
+            }
+        }
+    }
+
+    return shopperContextObj
+}