@W-20975885 New launch agent location in header component

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

@@ -87,6 +87,7 @@ import Seo from '@salesforce/retail-react-app/app/components/seo'
 import ShopperAgent from '@salesforce/retail-react-app/app/components/shopper-agent'
 import {getPathWithLocale} from '@salesforce/retail-react-app/app/utils/url'
 import {getCommerceAgentConfig} from '@salesforce/retail-react-app/app/utils/config-utils'
+import {useShopperAgent} from '@salesforce/retail-react-app/app/hooks/use-shopper-agent'
 
 const PlaceholderComponent = () => (
     <Center p="2">
@@ -285,6 +286,8 @@ const App = (props) => {
         history.push(path)
     }
 
+    const {actions: shopperAgentActions} = useShopperAgent()
+
     const trackPage = () => {
         activeData.trackPage(site.id, locale.id, currency)
     }
@@ -393,6 +396,7 @@ const App = (props) => {
                                                 onMyAccountClick={onAccountClick}
                                                 onWishlistClick={onWishlistClick}
                                                 onStoreLocatorClick={onOpenStoreLocator}
+                                                onAgentClick={shopperAgentActions.open}
                                             >
                                                 <HideOnDesktop>
                                                     <DrawerMenu

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

@@ -42,7 +42,8 @@ import {
     ChevronDownIcon,
     HeartIcon,
     SignoutIcon,
-    StoreIcon
+    StoreIcon,
+    SparkleIcon
 } from '@salesforce/retail-react-app/app/components/icons'
 
 import {navLinks, messages} from '@salesforce/retail-react-app/app/pages/account/constant'
@@ -52,6 +53,7 @@ import {HideOnDesktop, HideOnMobile} from '@salesforce/retail-react-app/app/comp
 import {isHydrated, noop} from '@salesforce/retail-react-app/app/utils/utils'
 import {STORE_LOCATOR_IS_ENABLED} from '@salesforce/retail-react-app/app/constants'
 import {getConfig} from '@salesforce/pwa-kit-runtime/utils/ssr-config'
+import {getCommerceAgentConfig} from '@salesforce/retail-react-app/app/utils/config-utils'
 const IconButtonWithRegistration = withRegistration(IconButton)
 
 /**
@@ -97,6 +99,7 @@ const SearchBar = (props) => {
  * @param   {object} props.searchInputRef reference of the search input
  * @param   {func} props.onMyAccountClick click event handler for my account button
  * @param   {func} props.onMyCartClick click event handler for my cart button
+ * @param   {func} props.onAgentClick click event handler for agent button
  * @return  {React.ReactElement} - Header component
  */
 const Header = ({
@@ -107,6 +110,7 @@ const Header = ({
     onMyCartClick = noop,
     onWishlistClick = noop,
     onStoreLocatorClick = noop,
+    onAgentClick = noop,
     ...props
 }) => {
     const intl = useIntl()
@@ -119,6 +123,8 @@ const Header = ({
     const logout = useAuthHelper(AuthHelpers.Logout)
     const navigate = useNavigation()
     const storeLocatorEnabled = getConfig()?.app?.storeLocatorEnabled ?? STORE_LOCATOR_IS_ENABLED
+    const commerceAgentConfig = getCommerceAgentConfig()
+    const showLaunchAgentButton = commerceAgentConfig?.enableAgentFromHeader === 'true'
     const {
         getButtonProps: getAccountMenuButtonProps,
         getDisclosureProps: getAccountMenuDisclosureProps,
@@ -191,6 +197,18 @@ const Header = ({
                     <HideOnMobile>
                         <SearchBar />
                     </HideOnMobile>
+                    {showLaunchAgentButton && (
+                        <IconButton
+                            icon={<SparkleIcon />}
+                            aria-label={intl.formatMessage({
+                                id: 'header.button.assistive_msg.ask_shopping_agent',
+                                defaultMessage: 'Ask Shopping Agent'
+                            })}
+                            variant="unstyled"
+                            {...styles.icons}
+                            onClick={onAgentClick}
+                        />
+                    )}
                     <IconButtonWithRegistration
                         icon={<AccountIcon />}
                         aria-label={intl.formatMessage({
@@ -362,6 +380,7 @@ Header.propTypes = {
     onWishlistClick: PropTypes.func,
     onMyCartClick: PropTypes.func,
     onStoreLocatorClick: PropTypes.func,
+    onAgentClick: PropTypes.func,
     searchInputRef: PropTypes.oneOfType([
         PropTypes.func,
         PropTypes.shape({current: PropTypes.elementType})

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

@@ -20,6 +20,7 @@ import {
     mockedRegisteredCustomer
 } from '@salesforce/retail-react-app/app/mocks/mock-data'
 import {useMediaQuery} from '@salesforce/retail-react-app/app/components/shared/ui'
+import {getCommerceAgentConfig} from '@salesforce/retail-react-app/app/utils/config-utils'
 
 jest.mock('@salesforce/retail-react-app/app/components/shared/ui', () => {
     const originalModule = jest.requireActual(
@@ -30,6 +31,10 @@ jest.mock('@salesforce/retail-react-app/app/components/shared/ui', () => {
         useMediaQuery: jest.fn().mockReturnValue([true])
     }
 })
+
+jest.mock('@salesforce/retail-react-app/app/utils/config-utils', () => ({
+    getCommerceAgentConfig: jest.fn()
+}))
 const MockedComponent = ({history}) => {
     const onAccountClick = () => {
         history.push(createPathWithDefaults('/account'))
@@ -55,6 +60,10 @@ beforeEach(() => {
             return res(ctx.delay(0), ctx.status(200), ctx.json(mockCustomerBaskets))
         })
     )
+    // Default mock for getCommerceAgentConfig
+    getCommerceAgentConfig.mockReturnValue({
+        enableAgentFromHeader: 'false'
+    })
 })
 afterEach(() => {
     localStorage.clear()
@@ -326,3 +335,102 @@ test('handles search functionality', async () => {
     fireEvent.change(searchInput, {target: {value: 'test search'}})
     expect(searchInput.value).toBe('test search')
 })
+
+describe('Agent button (SparkleIcon)', () => {
+    test('renders agent button when enableAgentFromHeader is true', async () => {
+        getCommerceAgentConfig.mockReturnValue({
+            enableAgentFromHeader: 'true'
+        })
+
+        renderWithProviders(<Header />)
+
+        await waitFor(() => {
+            const agentButton = screen.getByLabelText('Ask Shopping Agent')
+            expect(agentButton).toBeInTheDocument()
+        })
+    })
+
+    test('does not render agent button when enableAgentFromHeader is false', async () => {
+        getCommerceAgentConfig.mockReturnValue({
+            enableAgentFromHeader: 'false'
+        })
+
+        renderWithProviders(<Header />)
+
+        await waitFor(() => {
+            const agentButton = screen.queryByLabelText('Ask Shopping Agent')
+            expect(agentButton).not.toBeInTheDocument()
+        })
+    })
+
+    test('does not render agent button when enableAgentFromHeader is undefined', async () => {
+        getCommerceAgentConfig.mockReturnValue({
+            enableAgentFromHeader: undefined
+        })
+
+        renderWithProviders(<Header />)
+
+        await waitFor(() => {
+            const agentButton = screen.queryByLabelText('Ask Shopping Agent')
+            expect(agentButton).not.toBeInTheDocument()
+        })
+    })
+
+    test('does not render agent button when enableAgentFromHeader is not "true"', async () => {
+        getCommerceAgentConfig.mockReturnValue({
+            enableAgentFromHeader: 'someOtherValue'
+        })
+
+        renderWithProviders(<Header />)
+
+        await waitFor(() => {
+            const agentButton = screen.queryByLabelText('Ask Shopping Agent')
+            expect(agentButton).not.toBeInTheDocument()
+        })
+    })
+
+    test('calls onAgentClick when agent button is clicked', async () => {
+        const onAgentClick = jest.fn()
+        getCommerceAgentConfig.mockReturnValue({
+            enableAgentFromHeader: 'true'
+        })
+
+        renderWithProviders(<Header onAgentClick={onAgentClick} />)
+
+        await waitFor(() => {
+            const agentButton = screen.getByLabelText('Ask Shopping Agent')
+            expect(agentButton).toBeInTheDocument()
+        })
+
+        const agentButton = screen.getByLabelText('Ask Shopping Agent')
+        fireEvent.click(agentButton)
+
+        expect(onAgentClick).toHaveBeenCalledTimes(1)
+    })
+
+    test('agent button has correct aria-label', async () => {
+        getCommerceAgentConfig.mockReturnValue({
+            enableAgentFromHeader: 'true'
+        })
+
+        renderWithProviders(<Header />)
+
+        await waitFor(() => {
+            const agentButton = screen.getByLabelText('Ask Shopping Agent')
+            expect(agentButton).toBeInTheDocument()
+            expect(agentButton).toHaveAttribute('aria-label', 'Ask Shopping Agent')
+        })
+    })
+
+    test('calls getCommerceAgentConfig to check configuration', async () => {
+        getCommerceAgentConfig.mockReturnValue({
+            enableAgentFromHeader: 'true'
+        })
+
+        renderWithProviders(<Header />)
+
+        await waitFor(() => {
+            expect(getCommerceAgentConfig).toHaveBeenCalled()
+        })
+    })
+})

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

@@ -59,6 +59,7 @@ import '@salesforce/retail-react-app/app/assets/svg/visibility-off.svg'
 import '@salesforce/retail-react-app/app/assets/svg/heart.svg'
 import '@salesforce/retail-react-app/app/assets/svg/heart-solid.svg'
 import '@salesforce/retail-react-app/app/assets/svg/close.svg'
+import '@salesforce/retail-react-app/app/assets/svg/sparkle.svg'
 
 // For non-square SVGs, we can use the symbol data from the import to set the
 // proper viewBox attribute on the Icon wrapper.
@@ -199,6 +200,7 @@ export const SocialPinterestIcon = icon('social-pinterest', {
 })
 export const SocialTwitterIcon = icon('social-twitter')
 export const SocialYoutubeIcon = icon('social-youtube')
+export const SparkleIcon = icon('sparkle')
 export const StoreIcon = icon('store')
 export const SignoutIcon = icon('signout')
 export const UserIcon = icon('user')

packages/template-retail-react-app/app/hooks/use-shopper-agent.js

@@ -0,0 +1,20 @@
+/*
+ * Copyright (c) 2025, Salesforce, 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 {useCallback} from 'react'
+import {launchChat} from '@salesforce/retail-react-app/app/utils/shopper-agent-utils'
+
+/**
+ * React hook that returns shopper agent actions.
+ * Uses the embedded service bootstrap API. Structured for future extension (e.g. close, sendMessage).
+ */
+export function useShopperAgent() {
+    const open = useCallback(() => {
+        launchChat()
+    }, [])
+
+    return {actions: {open}}
+}

packages/template-retail-react-app/app/hooks/use-shopper-agent.test.js

@@ -0,0 +1,59 @@
+/*
+ * Copyright (c) 2025, Salesforce, 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 {renderHook, act} from '@testing-library/react'
+import {useShopperAgent} from '@salesforce/retail-react-app/app/hooks/use-shopper-agent'
+import {launchChat} from '@salesforce/retail-react-app/app/utils/shopper-agent-utils'
+
+jest.mock('@salesforce/retail-react-app/app/utils/shopper-agent-utils', () => ({
+    launchChat: jest.fn()
+}))
+
+describe('useShopperAgent', () => {
+    beforeEach(() => {
+        jest.clearAllMocks()
+    })
+
+    test('should return an object with actions', () => {
+        const {result} = renderHook(() => useShopperAgent())
+
+        expect(result.current).toEqual({actions: expect.any(Object)})
+        expect(result.current.actions).toHaveProperty('open')
+        expect(typeof result.current.actions.open).toBe('function')
+    })
+
+    test('should call launchChat when actions.open is invoked', () => {
+        const {result} = renderHook(() => useShopperAgent())
+
+        act(() => {
+            result.current.actions.open()
+        })
+
+        expect(launchChat).toHaveBeenCalledTimes(1)
+    })
+
+    test('should call launchChat each time actions.open is invoked', () => {
+        const {result} = renderHook(() => useShopperAgent())
+
+        act(() => {
+            result.current.actions.open()
+            result.current.actions.open()
+        })
+
+        expect(launchChat).toHaveBeenCalledTimes(2)
+    })
+
+    test('should return a stable open callback reference across re-renders', () => {
+        const {result, rerender} = renderHook(() => useShopperAgent())
+
+        const firstOpen = result.current.actions.open
+        rerender()
+        const secondOpen = result.current.actions.open
+
+        expect(firstOpen).toBe(secondOpen)
+    })
+})

packages/template-retail-react-app/app/static/translations/compiled/en-GB.json

@@ -1955,6 +1955,12 @@
       "value": "View"
     }
   ],
+  "header.button.assistive_msg.ask_shopping_agent": [
+    {
+      "type": 0,
+      "value": "Ask Shopping Agent"
+    }
+  ],
   "header.button.assistive_msg.logo": [
     {
       "type": 0,

packages/template-retail-react-app/app/static/translations/compiled/en-US.json

@@ -1955,6 +1955,12 @@
       "value": "View"
     }
   ],
+  "header.button.assistive_msg.ask_shopping_agent": [
+    {
+      "type": 0,
+      "value": "Ask Shopping Agent"
+    }
+  ],
   "header.button.assistive_msg.logo": [
     {
       "type": 0,

packages/template-retail-react-app/app/static/translations/compiled/en-XA.json

@@ -3987,6 +3987,20 @@
       "value": "]"
     }
   ],
+  "header.button.assistive_msg.ask_shopping_agent": [
+    {
+      "type": 0,
+      "value": "["
+    },
+    {
+      "type": 0,
+      "value": "Ȧşķ Şħǿǿƥƥīƞɠ Ȧɠḗḗƞŧ"
+    },
+    {
+      "type": 0,
+      "value": "]"
+    }
+  ],
   "header.button.assistive_msg.logo": [
     {
       "type": 0,

packages/template-retail-react-app/app/utils/config-utils.js

@@ -19,7 +19,8 @@ export const getCommerceAgentConfig = () => {
         commerceOrgId: '',
         siteId: '',
         enableConversationContext: 'false',
-        conversationContext: []
+        conversationContext: [],
+        enableAgentFromHeader: 'false'
     }
     return getConfig().app.commerceAgent ?? defaults
 }