@salesforce/retail-react-app 8.3.0-nightly-20251209080224 → 8.3.0-preview.0

package/CHANGELOG.md

@@ -1,5 +1,6 @@
-## v8.3.0-dev (Nov 05, 2025)
+## v8.3.0-preview.0 (Dec 12, 2025)
 - [Bugfix] Fix Forgot Password link not working from Account Profile password update form [#3493](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3493)
+- Introduce Address Autocompletion feature in the checkout flow, powered by Google Maps Platform [#3071](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3071)
 
 ## v8.2.0 (Nov 04, 2025)
 - Add support for Rule Based Promotions for Choice of Bonus Products. We are currently supporting only one product level rule based promotion per product [#3418](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3418)

package/app/components/address-suggestion-dropdown/index.jsx

@@ -0,0 +1,189 @@
+/*
+ * Copyright (c) 2025, 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 React, {useEffect, useRef} from 'react'
+import PropTypes from 'prop-types'
+import {FormattedMessage} from 'react-intl'
+import {getAssetUrl} from '@salesforce/pwa-kit-react-sdk/ssr/universal/utils'
+import {
+    Box,
+    Flex,
+    Text,
+    IconButton,
+    Spinner,
+    Stack,
+    Spacer
+} from '@salesforce/retail-react-app/app/components/shared/ui'
+import {CloseIcon, LocationIcon} from '@salesforce/retail-react-app/app/components/icons'
+
+/**
+ * Address Suggestion Dropdown Component
+ * Displays Google-powered address suggestions in a dropdown format
+ */
+const AddressSuggestionDropdown = ({
+    suggestions = [],
+    isLoading = false,
+    onClose,
+    onSelectSuggestion,
+    isVisible = false,
+    position = 'absolute'
+}) => {
+    const dropdownRef = useRef(null)
+
+    useEffect(() => {
+        const handleClickOutside = (event) => {
+            if (dropdownRef.current && !dropdownRef.current.contains(event.target)) {
+                onClose()
+            }
+        }
+
+        if (isVisible) {
+            document.addEventListener('mousedown', handleClickOutside)
+        }
+
+        return () => {
+            document.removeEventListener('mousedown', handleClickOutside)
+        }
+    }, [isVisible, onClose])
+
+    if (!isVisible || suggestions.length === 0) {
+        return null
+    }
+
+    if (isLoading) {
+        return (
+            <Box
+                position="absolute"
+                top="100%"
+                left={0}
+                right={0}
+                bg="white"
+                border="1px solid"
+                borderColor="gray.200"
+                borderRadius="md"
+                boxShadow="md"
+                zIndex={1000}
+                p={4}
+            >
+                <Flex align="center" justify="center">
+                    <Spinner size="sm" mr={2} />
+                    <Text>Loading suggestions...</Text>
+                </Flex>
+            </Box>
+        )
+    }
+
+    return (
+        <Box
+            ref={dropdownRef}
+            data-testid="address-suggestion-dropdown"
+            position={position}
+            top="100%"
+            left={0}
+            right={0}
+            zIndex={1000}
+            bg="white"
+            border="1px solid"
+            borderColor="gray.200"
+            borderRadius="md"
+            boxShadow="md"
+            mt={1}
+        >
+            <Flex px={4} pr={0} py={2} alignItems="center">
+                <Text fontSize="sm" fontWeight="medium" color="gray.600">
+                    <FormattedMessage
+                        defaultMessage="SUGGESTED"
+                        id="addressSuggestionDropdown.suggested"
+                    />
+                </Text>
+                <Spacer />
+                <IconButton
+                    size="sm"
+                    variant="ghost"
+                    icon={<CloseIcon boxSize={4} color="gray.600" />}
+                    onClick={onClose}
+                    aria-label="Close suggestions"
+                />
+            </Flex>
+            <Stack spacing={0}>
+                {suggestions.map((suggestion, index) => (
+                    <Box
+                        key={index}
+                        px={4}
+                        py={3}
+                        cursor="pointer"
+                        _hover={{bg: 'gray.50'}}
+                        onClick={() => onSelectSuggestion(suggestion)}
+                        role="button"
+                        tabIndex={0}
+                        onKeyDown={(e) => {
+                            if (e.key === 'Enter' || e.key === ' ') {
+                                onSelectSuggestion(suggestion)
+                            }
+                        }}
+                    >
+                        <Flex alignItems="center" gap={2}>
+                            <LocationIcon boxSize={4} color="black" />
+                            <Box flex={1}>
+                                <Text fontSize="sm" noOfLines={1}>
+                                    {suggestion.description ||
+                                        `${suggestion.structured_formatting?.main_text}, ${suggestion.structured_formatting?.secondary_text}`}
+                                </Text>
+                            </Box>
+                        </Flex>
+                    </Box>
+                ))}
+            </Stack>
+
+            <Box px={4} py={3} display="flex" alignItems="center">
+                <img
+                    src={getAssetUrl('static/img/GoogleMaps_Logo_Gray_4x.png')}
+                    alt="Google Maps"
+                    style={{width: '98px', height: '18px'}}
+                />
+            </Box>
+        </Box>
+    )
+}
+
+AddressSuggestionDropdown.propTypes = {
+    /** Array of address suggestions to display */
+    suggestions: PropTypes.arrayOf(
+        PropTypes.shape({
+            description: PropTypes.string,
+            place_id: PropTypes.string,
+            structured_formatting: PropTypes.shape({
+                main_text: PropTypes.string,
+                secondary_text: PropTypes.string
+            }),
+            terms: PropTypes.arrayOf(
+                PropTypes.shape({
+                    offset: PropTypes.number,
+                    value: PropTypes.string
+                })
+            ),
+            types: PropTypes.arrayOf(PropTypes.string),
+            placePrediction: PropTypes.object
+        })
+    ),
+
+    /** Whether the dropdown should be visible */
+    isVisible: PropTypes.bool,
+
+    /** Callback when close button is clicked */
+    onClose: PropTypes.func.isRequired,
+
+    /** Callback when a suggestion is selected */
+    onSelectSuggestion: PropTypes.func.isRequired,
+
+    /** CSS position property for the dropdown */
+    position: PropTypes.oneOf(['absolute', 'relative', 'fixed']),
+
+    /** Whether the dropdown is loading */
+    isLoading: PropTypes.bool
+}
+
+export default AddressSuggestionDropdown

package/app/components/address-suggestion-dropdown/index.test.jsx

@@ -0,0 +1,332 @@
+/*
+ * Copyright (c) 2025, 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 React from 'react'
+import {render, screen, fireEvent} from '@testing-library/react'
+import {IntlProvider} from 'react-intl'
+import '@testing-library/jest-dom'
+import AddressSuggestionDropdown from '@salesforce/retail-react-app/app/components/address-suggestion-dropdown/index'
+
+describe('AddressSuggestionDropdown', () => {
+    const mockSuggestions = [
+        {
+            description: '123 Main Street, New York, NY 10001, USA',
+            place_id: 'ChIJ1234567890',
+            structured_formatting: {
+                main_text: '123 Main Street',
+                secondary_text: 'New York, NY 10001, USA'
+            },
+            terms: [
+                {value: '123 Main Street'},
+                {value: 'New York'},
+                {value: 'NY'},
+                {value: '10001'},
+                {value: 'USA'}
+            ],
+            placePrediction: {
+                text: {text: '123 Main Street, New York, NY 10001, USA'},
+                placeId: 'ChIJ1234567890'
+            }
+        },
+        {
+            description: '456 Oak Avenue, Los Angeles, CA 90210, USA',
+            place_id: 'ChIJ4567890123',
+            structured_formatting: {
+                main_text: '456 Oak Avenue',
+                secondary_text: 'Los Angeles, CA 90210, USA'
+            },
+            terms: [
+                {value: '456 Oak Avenue'},
+                {value: 'Los Angeles'},
+                {value: 'CA'},
+                {value: '90210'},
+                {value: 'USA'}
+            ],
+            placePrediction: {
+                text: {text: '456 Oak Avenue, Los Angeles, CA 90210, USA'},
+                placeId: 'ChIJ4567890123'
+            }
+        }
+    ]
+
+    const defaultProps = {
+        suggestions: [],
+        isLoading: false,
+        isVisible: false,
+        onClose: jest.fn(),
+        onSelectSuggestion: jest.fn()
+    }
+
+    const renderWithIntl = (component) => {
+        return render(
+            <IntlProvider locale="en" messages={{}}>
+                {component}
+            </IntlProvider>
+        )
+    }
+
+    beforeEach(() => {
+        jest.clearAllMocks()
+    })
+
+    it('should not render when isVisible is false', () => {
+        renderWithIntl(<AddressSuggestionDropdown {...defaultProps} />)
+
+        expect(screen.queryByTestId('address-suggestion-dropdown')).not.toBeInTheDocument()
+    })
+
+    it('should render dropdown when isVisible is true', () => {
+        renderWithIntl(
+            <AddressSuggestionDropdown
+                {...defaultProps}
+                isVisible={true}
+                suggestions={mockSuggestions}
+            />
+        )
+
+        expect(screen.getByTestId('address-suggestion-dropdown')).toBeInTheDocument()
+    })
+
+    it('should render loading state when isLoading is true', () => {
+        renderWithIntl(
+            <AddressSuggestionDropdown
+                {...defaultProps}
+                isVisible={true}
+                isLoading={true}
+                suggestions={[
+                    {
+                        description: 'dummy',
+                        place_id: 'dummy',
+                        structured_formatting: {
+                            main_text: 'dummy',
+                            secondary_text: 'dummy'
+                        },
+                        terms: [],
+                        placePrediction: {
+                            text: {text: 'dummy'},
+                            placeId: 'dummy'
+                        }
+                    }
+                ]}
+            />
+        )
+
+        expect(screen.getByText('Loading suggestions...')).toBeInTheDocument()
+    })
+
+    it('should render suggestions when provided', () => {
+        renderWithIntl(
+            <AddressSuggestionDropdown
+                {...defaultProps}
+                isVisible={true}
+                suggestions={mockSuggestions}
+            />
+        )
+
+        expect(screen.getByText('123 Main Street, New York, NY 10001, USA')).toBeInTheDocument()
+        expect(screen.getByText('456 Oak Avenue, Los Angeles, CA 90210, USA')).toBeInTheDocument()
+    })
+
+    it('should call onSelectSuggestion when a suggestion is clicked', () => {
+        const mockOnSelect = jest.fn()
+        renderWithIntl(
+            <AddressSuggestionDropdown
+                {...defaultProps}
+                isVisible={true}
+                suggestions={mockSuggestions}
+                onSelectSuggestion={mockOnSelect}
+            />
+        )
+
+        fireEvent.click(screen.getByText('123 Main Street, New York, NY 10001, USA'))
+
+        expect(mockOnSelect).toHaveBeenCalledWith(mockSuggestions[0])
+    })
+
+    it('should call onSelectSuggestion when Enter key is pressed on a suggestion', () => {
+        const mockOnSelect = jest.fn()
+        renderWithIntl(
+            <AddressSuggestionDropdown
+                {...defaultProps}
+                isVisible={true}
+                suggestions={mockSuggestions}
+                onSelectSuggestion={mockOnSelect}
+            />
+        )
+
+        const firstSuggestion = screen
+            .getByText('123 Main Street, New York, NY 10001, USA')
+            .closest('[role="button"]')
+        fireEvent.keyDown(firstSuggestion, {key: 'Enter', code: 'Enter'})
+
+        expect(mockOnSelect).toHaveBeenCalledWith(mockSuggestions[0])
+    })
+
+    it('should call onClose when close button is clicked', () => {
+        const mockOnClose = jest.fn()
+        renderWithIntl(
+            <AddressSuggestionDropdown
+                {...defaultProps}
+                isVisible={true}
+                suggestions={mockSuggestions}
+                onClose={mockOnClose}
+            />
+        )
+
+        const closeButton = screen.getByLabelText('Close suggestions')
+        fireEvent.click(closeButton)
+
+        expect(mockOnClose).toHaveBeenCalled()
+    })
+
+    it('should handle empty suggestions array', () => {
+        renderWithIntl(
+            <AddressSuggestionDropdown {...defaultProps} isVisible={true} suggestions={[]} />
+        )
+
+        expect(screen.queryByTestId('address-suggestion-dropdown')).not.toBeInTheDocument()
+    })
+
+    it('should handle suggestions with missing secondaryText', () => {
+        const suggestionsWithoutSecondary = [
+            {
+                description: '123 Main Street',
+                place_id: 'ChIJ1234567890',
+                structured_formatting: {
+                    main_text: '123 Main Street',
+                    secondary_text: null
+                },
+                terms: [{offset: 0, value: '123 Main Street'}],
+                types: ['street_address']
+            }
+        ]
+
+        renderWithIntl(
+            <AddressSuggestionDropdown
+                {...defaultProps}
+                isVisible={true}
+                suggestions={suggestionsWithoutSecondary}
+            />
+        )
+
+        expect(screen.getByText('123 Main Street')).toBeInTheDocument()
+    })
+
+    it('should handle keyboard navigation', () => {
+        const mockOnSelect = jest.fn()
+        renderWithIntl(
+            <AddressSuggestionDropdown
+                {...defaultProps}
+                isVisible={true}
+                suggestions={mockSuggestions}
+                onSelectSuggestion={mockOnSelect}
+            />
+        )
+
+        const firstSuggestion = screen
+            .getByText('123 Main Street, New York, NY 10001, USA')
+            .closest('[role="button"]')
+        fireEvent.keyDown(firstSuggestion, {key: 'Enter', code: 'Enter'})
+
+        expect(mockOnSelect).toHaveBeenCalledWith(mockSuggestions[0])
+    })
+
+    it('should handle mouse hover on suggestions', () => {
+        const mockOnSelect = jest.fn()
+        renderWithIntl(
+            <AddressSuggestionDropdown
+                {...defaultProps}
+                isVisible={true}
+                suggestions={mockSuggestions}
+                onSelectSuggestion={mockOnSelect}
+            />
+        )
+
+        const firstSuggestion = screen
+            .getByText('123 Main Street, New York, NY 10001, USA')
+            .closest('[role="button"]')
+
+        // Verify element exists before hover
+        expect(firstSuggestion).toBeInTheDocument()
+
+        // Simulate hover events
+        fireEvent.mouseEnter(firstSuggestion)
+        fireEvent.mouseLeave(firstSuggestion)
+
+        // Verify element is still present and functional after hover
+        expect(firstSuggestion).toBeInTheDocument()
+        expect(firstSuggestion).toHaveAttribute('role', 'button')
+
+        // Verify the suggestion is still clickable after hover
+        fireEvent.click(firstSuggestion)
+        expect(mockOnSelect).toHaveBeenCalledWith(mockSuggestions[0])
+    })
+
+    it('should display Google Maps placePrediction data correctly', () => {
+        const googleMapsSuggestions = [
+            {
+                description: '123 Main St, New York, NY 10001, USA',
+                place_id: 'test-place-id',
+                structured_formatting: {
+                    main_text: '123 Main St',
+                    secondary_text: 'New York, NY 10001, USA'
+                },
+                terms: [
+                    {value: '123 Main St'},
+                    {value: 'New York'},
+                    {value: 'NY'},
+                    {value: '10001'},
+                    {value: 'USA'}
+                ],
+                placePrediction: {
+                    text: {text: '123 Main St, New York, NY 10001, USA'},
+                    placeId: 'test-place-id'
+                }
+            }
+        ]
+
+        renderWithIntl(
+            <AddressSuggestionDropdown
+                {...defaultProps}
+                isVisible={true}
+                suggestions={googleMapsSuggestions}
+            />
+        )
+
+        expect(screen.getByText('123 Main St, New York, NY 10001, USA')).toBeInTheDocument()
+    })
+
+    it('should fallback to structured_formatting when placePrediction is not available', () => {
+        const fallbackSuggestions = [
+            {
+                description: '123 Main St, New York, NY 10001, USA',
+                place_id: 'test-place-id',
+                structured_formatting: {
+                    main_text: '123 Main St',
+                    secondary_text: 'New York, NY 10001, USA'
+                },
+                terms: [
+                    {value: '123 Main St'},
+                    {value: 'New York'},
+                    {value: 'NY'},
+                    {value: '10001'},
+                    {value: 'USA'}
+                ]
+            }
+        ]
+
+        renderWithIntl(
+            <AddressSuggestionDropdown
+                {...defaultProps}
+                isVisible={true}
+                suggestions={fallbackSuggestions}
+            />
+        )
+
+        expect(screen.getByText('123 Main St, New York, NY 10001, USA')).toBeInTheDocument()
+    })
+})

package/app/components/forms/address-fields.jsx

@@ -11,12 +11,14 @@ import {
     Grid,
     GridItem,
     SimpleGrid,
-    Stack
+    Stack,
+    Box
 } from '@salesforce/retail-react-app/app/components/shared/ui'
 import useAddressFields from '@salesforce/retail-react-app/app/components/forms/useAddressFields'
 import Field from '@salesforce/retail-react-app/app/components/field'
 import {useCurrentCustomer} from '@salesforce/retail-react-app/app/hooks/use-current-customer'
 import {MESSAGE_PROPTYPE} from '@salesforce/retail-react-app/app/utils/locale'
+import AddressSuggestionDropdown from '@salesforce/retail-react-app/app/components/address-suggestion-dropdown'
 
 const defaultFormTitleAriaLabel = defineMessage({
     defaultMessage: 'Address Form',
@@ -51,7 +53,21 @@ const AddressFields = ({
             </SimpleGrid>
             <Field {...fields.phone} />
             <Field {...fields.countryCode} />
-            <Field {...fields.address1} />
+
+            <Box position="relative">
+                <Field {...fields.address1} />
+                <AddressSuggestionDropdown
+                    suggestions={fields.address1.autocomplete.suggestions}
+                    isVisible={
+                        fields.address1.autocomplete.showDropdown &&
+                        !fields.address1.autocomplete.isDismissed
+                    }
+                    onClose={fields.address1.autocomplete.onClose}
+                    onSelectSuggestion={fields.address1.autocomplete.onSelectSuggestion}
+                    position="absolute"
+                />
+            </Box>
+
             <Field {...fields.city} />
             <Grid templateColumns="repeat(8, 1fr)" gap={5}>
                 <GridItem colSpan={[4, 4, 4]}>