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

package/app/components/forms/useAddressFields.jsx

@@ -5,12 +5,18 @@
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
  */
 import {useIntl, defineMessages} from 'react-intl'
+import {useState, useCallback, useEffect} from 'react'
 import {formatPhoneNumber} from '@salesforce/retail-react-app/app/utils/phone-utils'
 import {
     stateOptions,
     provinceOptions
 } from '@salesforce/retail-react-app/app/components/forms/state-province-options'
 import {SHIPPING_COUNTRY_CODES} from '@salesforce/retail-react-app/app/constants'
+import {
+    processAddressSuggestion,
+    setAddressFieldValues
+} from '@salesforce/retail-react-app/app/utils/address-suggestions'
+import {useAutocompleteSuggestions} from '@salesforce/retail-react-app/app/hooks/useAutocompleteSuggestions'
 
 const messages = defineMessages({
     required: {defaultMessage: 'Required', id: 'use_address_fields.error.required'},
@@ -42,14 +48,128 @@ export default function useAddressFields({
     form: {
         watch,
         control,
+        setValue,
         formState: {errors}
     },
     prefix = ''
 }) {
     const {formatMessage} = useIntl()
 
+    const [showDropdown, setShowDropdown] = useState(false)
+    const [isDismissed, setIsDismissed] = useState(false)
+    const [currentInput, setCurrentInput] = useState('')
+    const [isAutocompleted, setIsAutocompleted] = useState(false)
+    const [previousCountry, setPreviousCountry] = useState(undefined)
+
     const countryCode = watch('countryCode')
 
+    const {suggestions, isLoading, resetSession} = useAutocompleteSuggestions(
+        currentInput,
+        countryCode
+    )
+
+    const clearAddressFields = useCallback(() => {
+        setValue(`${prefix}address1`, '')
+        setValue(`${prefix}city`, '')
+        setValue(`${prefix}stateCode`, '')
+        setValue(`${prefix}postalCode`, '')
+        setCurrentInput('')
+        setShowDropdown(false)
+        setIsDismissed(false)
+        resetSession()
+    }, [prefix, setValue, resetSession])
+
+    useEffect(() => {
+        if (isAutocompleted) {
+            return
+        }
+
+        // Only clear fields if the country actually changed from a previous value (not initial load)
+        if (countryCode && previousCountry !== undefined && countryCode !== previousCountry) {
+            clearAddressFields()
+        }
+
+        setPreviousCountry(countryCode)
+    }, [countryCode, clearAddressFields, isAutocompleted, previousCountry])
+
+    const handleAddressInputChange = useCallback((value) => {
+        setCurrentInput(value)
+
+        if (!value || value.length < 3) {
+            setShowDropdown(false)
+        } else {
+            setShowDropdown(true)
+            setIsDismissed(false)
+        }
+    }, [])
+
+    const handleAddressFocus = useCallback(() => {
+        setIsDismissed(false) // Reset dismissal on new focus
+    }, [])
+
+    const handleAddressCut = useCallback(
+        (e) => {
+            const newValue = e.target.value
+            handleAddressInputChange(newValue)
+        },
+        [handleAddressInputChange]
+    )
+
+    useEffect(() => {
+        const handleClickOutside = (event) => {
+            const addressInput = document.querySelector(`input[name="${prefix}address1"]`)
+            const dropdown = document.querySelector('[data-testid="address-suggestion-dropdown"]')
+
+            if (
+                addressInput &&
+                dropdown &&
+                !addressInput.contains(event.target) &&
+                !dropdown.contains(event.target)
+            ) {
+                setShowDropdown(false)
+                setIsDismissed(true)
+                resetSession()
+            }
+        }
+
+        document.addEventListener('mousedown', handleClickOutside)
+
+        return () => {
+            document.removeEventListener('mousedown', handleClickOutside)
+        }
+    }, [prefix, setShowDropdown, setIsDismissed, resetSession])
+
+    const handleDropdownClose = useCallback(() => {
+        setShowDropdown(false)
+        setIsDismissed(true)
+        resetSession()
+    }, [setShowDropdown, setIsDismissed, resetSession])
+
+    const handleSuggestionSelect = useCallback(
+        async (suggestion) => {
+            try {
+                setIsAutocompleted(true)
+
+                const addressFields = await processAddressSuggestion(suggestion)
+
+                setAddressFieldValues(setValue, prefix, addressFields)
+
+                resetSession()
+                setShowDropdown(false)
+                setIsDismissed(true)
+                setCurrentInput('')
+
+                setTimeout(() => {
+                    setIsAutocompleted(false)
+                }, 100)
+            } catch (error) {
+                console.error('Error parsing address suggestion:', error)
+                setIsAutocompleted(false)
+            }
+        },
+        [prefix, setValue, resetSession, setIsAutocompleted]
+    )
+
     const fields = {
         firstName: {
             name: `${prefix}firstName`,
@@ -130,7 +250,25 @@ export default function useAddressFields({
                 })
             },
             error: errors[`${prefix}address1`],
-            control
+            control,
+            inputProps: ({onChange}) => ({
+                onChange(evt) {
+                    onChange(evt.target.value)
+                    handleAddressInputChange(evt.target.value)
+                },
+                onFocus: handleAddressFocus,
+                onCut: handleAddressCut
+            }),
+            autocomplete: {
+                suggestions,
+                showDropdown,
+                isLoading,
+                isDismissed,
+                onInputChange: handleAddressInputChange,
+                onFocus: handleAddressFocus,
+                onClose: handleDropdownClose,
+                onSelectSuggestion: handleSuggestionSelect
+            }
         },
         city: {
             name: `${prefix}city`,

package/app/components/forms/useAddressFields.test.js

@@ -0,0 +1,310 @@
+/*
+ * 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 {renderHook, act} from '@testing-library/react'
+import useAddressFields from '../forms/useAddressFields'
+import {
+    processAddressSuggestion,
+    setAddressFieldValues
+} from '@salesforce/retail-react-app/app/utils/address-suggestions'
+import {useAutocompleteSuggestions} from '@salesforce/retail-react-app/app/hooks/useAutocompleteSuggestions'
+
+jest.mock('@salesforce/retail-react-app/app/utils/address-suggestions')
+
+jest.mock('@salesforce/retail-react-app/app/hooks/useAutocompleteSuggestions', () => ({
+    useAutocompleteSuggestions: jest.fn()
+}))
+
+jest.mock('react-intl', () => ({
+    useIntl: () => ({
+        formatMessage: jest.fn((message) => message.defaultMessage || message.id)
+    }),
+    defineMessages: jest.fn((messages) => messages)
+}))
+
+jest.mock('@salesforce/retail-react-app/app/utils/phone-utils', () => ({
+    formatPhoneNumber: jest.fn((value) => value)
+}))
+
+jest.mock('@salesforce/retail-react-app/app/components/forms/state-province-options', () => ({
+    stateOptions: [
+        {value: 'NY', label: 'New York'},
+        {value: 'CA', label: 'California'}
+    ],
+    provinceOptions: [
+        {value: 'ON', label: 'Ontario'},
+        {value: 'BC', label: 'British Columbia'}
+    ]
+}))
+
+jest.mock('@salesforce/retail-react-app/app/constants', () => ({
+    SHIPPING_COUNTRY_CODES: [
+        {value: 'US', label: 'United States'},
+        {value: 'CA', label: 'Canada'}
+    ]
+}))
+
+describe('useAddressFields', () => {
+    let mockForm
+    let mockSetValue
+    let mockWatch
+    let mockUseAutocompleteSuggestions
+
+    beforeEach(() => {
+        jest.clearAllMocks()
+
+        mockSetValue = jest.fn()
+        mockWatch = jest.fn()
+
+        mockForm = {
+            watch: mockWatch,
+            control: {},
+            setValue: mockSetValue,
+            formState: {errors: {}}
+        }
+
+        mockUseAutocompleteSuggestions = {
+            suggestions: [],
+            isLoading: false,
+            resetSession: jest.fn()
+        }
+
+        useAutocompleteSuggestions.mockReturnValue(mockUseAutocompleteSuggestions)
+
+        processAddressSuggestion.mockResolvedValue({
+            address1: '123 Main Street',
+            city: 'New York',
+            stateCode: 'NY',
+            postalCode: '10001',
+            countryCode: 'US'
+        })
+
+        setAddressFieldValues.mockImplementation((setValue, prefix, addressFields) => {
+            setValue(`${prefix}address1`, addressFields.address1)
+            if (addressFields.city) {
+                setValue(`${prefix}city`, addressFields.city)
+            }
+            if (addressFields.stateCode) {
+                setValue(`${prefix}stateCode`, addressFields.stateCode)
+            }
+            if (addressFields.postalCode) {
+                setValue(`${prefix}postalCode`, addressFields.postalCode)
+            }
+            if (addressFields.countryCode) {
+                setValue(`${prefix}countryCode`, addressFields.countryCode)
+            }
+        })
+    })
+
+    it('should return all required address fields', () => {
+        const {result} = renderHook(() => useAddressFields({form: mockForm}))
+
+        expect(result.current).toHaveProperty('firstName')
+        expect(result.current).toHaveProperty('lastName')
+        expect(result.current).toHaveProperty('phone')
+        expect(result.current).toHaveProperty('countryCode')
+        expect(result.current).toHaveProperty('address1')
+        expect(result.current).toHaveProperty('city')
+        expect(result.current).toHaveProperty('stateCode')
+        expect(result.current).toHaveProperty('postalCode')
+        expect(result.current).toHaveProperty('preferred')
+    })
+
+    it('should set default country to US', () => {
+        const {result} = renderHook(() => useAddressFields({form: mockForm}))
+
+        expect(result.current.countryCode.defaultValue).toBe('US')
+    })
+
+    it('should handle address input changes', () => {
+        const {result} = renderHook(() => useAddressFields({form: mockForm}))
+
+        act(() => {
+            const inputProps = result.current.address1.inputProps({onChange: jest.fn()})
+            inputProps.onChange({
+                target: {value: '123 Main'}
+            })
+        })
+
+        expect(result.current.address1.autocomplete).toBeDefined()
+    })
+
+    it('should handle address input changes for short input', () => {
+        const {result} = renderHook(() => useAddressFields({form: mockForm}))
+
+        act(() => {
+            const inputProps = result.current.address1.inputProps({onChange: jest.fn()})
+            inputProps.onChange({
+                target: {value: '12'}
+            })
+        })
+
+        expect(result.current.address1.autocomplete).toBeDefined()
+    })
+
+    it('should populate all address fields when suggestion is selected', async () => {
+        const {result} = renderHook(() => useAddressFields({form: mockForm}))
+
+        const suggestion = {
+            mainText: '123 Main Street',
+            secondaryText: 'New York, NY 10001, USA',
+            country: 'US'
+        }
+
+        await act(async () => {
+            await result.current.address1.autocomplete.onSelectSuggestion(suggestion)
+        })
+
+        expect(processAddressSuggestion).toHaveBeenCalledWith(suggestion)
+        expect(setAddressFieldValues).toHaveBeenCalledWith(mockSetValue, '', {
+            address1: '123 Main Street',
+            city: 'New York',
+            stateCode: 'NY',
+            postalCode: '10001',
+            countryCode: 'US'
+        })
+    })
+
+    it('should handle partial address data when some fields are missing', async () => {
+        const {result} = renderHook(() => useAddressFields({form: mockForm}))
+
+        processAddressSuggestion.mockResolvedValue({
+            address1: '456 Oak Avenue',
+            city: 'Toronto'
+        })
+
+        const suggestion = {
+            mainText: '456 Oak Avenue',
+            secondaryText: 'Toronto, Canada',
+            country: 'CA'
+        }
+
+        await act(async () => {
+            await result.current.address1.autocomplete.onSelectSuggestion(suggestion)
+        })
+
+        expect(processAddressSuggestion).toHaveBeenCalledWith(suggestion)
+        expect(setAddressFieldValues).toHaveBeenCalledWith(mockSetValue, '', {
+            address1: '456 Oak Avenue',
+            city: 'Toronto'
+        })
+    })
+
+    it('should handle address focus correctly', () => {
+        const {result} = renderHook(() => useAddressFields({form: mockForm}))
+
+        act(() => {
+            const inputProps = result.current.address1.inputProps({onChange: jest.fn()})
+            inputProps.onFocus()
+        })
+
+        expect(result.current.address1.autocomplete).toBeDefined()
+    })
+
+    it('should handle address cut event', () => {
+        const {result} = renderHook(() => useAddressFields({form: mockForm}))
+
+        act(() => {
+            const inputProps = result.current.address1.inputProps({onChange: jest.fn()})
+            inputProps.onCut({
+                target: {value: '123 Main'}
+            })
+        })
+
+        expect(result.current.address1.autocomplete).toBeDefined()
+    })
+
+    it('should close dropdown when onClose is called', () => {
+        const {result} = renderHook(() => useAddressFields({form: mockForm}))
+
+        act(() => {
+            result.current.address1.autocomplete.onClose()
+        })
+
+        expect(result.current.address1.autocomplete).toBeDefined()
+        expect(result.current.address1.autocomplete.onClose).toBeDefined()
+    })
+
+    it('should handle country change and reset address fields', () => {
+        let callCount = 0
+        mockWatch.mockImplementation(() => {
+            callCount++
+            return callCount === 1 ? 'US' : 'CA'
+        })
+
+        const {rerender} = renderHook(() => useAddressFields({form: mockForm}))
+
+        rerender()
+
+        expect(mockSetValue).toHaveBeenCalledWith('address1', '')
+        expect(mockSetValue).toHaveBeenCalledWith('city', '')
+        expect(mockSetValue).toHaveBeenCalledWith('stateCode', '')
+        expect(mockSetValue).toHaveBeenCalledWith('postalCode', '')
+
+        expect(mockUseAutocompleteSuggestions.resetSession).toHaveBeenCalled()
+    })
+
+    it('should use prefix for field names when provided', () => {
+        const {result} = renderHook(() =>
+            useAddressFields({
+                form: mockForm,
+                prefix: 'shipping'
+            })
+        )
+
+        expect(result.current.firstName.name).toBe('shippingfirstName')
+        expect(result.current.lastName.name).toBe('shippinglastName')
+        expect(result.current.address1.name).toBe('shippingaddress1')
+    })
+
+    it('should handle phone number formatting', () => {
+        const {result} = renderHook(() => useAddressFields({form: mockForm}))
+
+        const mockOnChange = jest.fn()
+
+        act(() => {
+            result.current.phone.inputProps({onChange: mockOnChange}).onChange({
+                target: {value: '1234567890'}
+            })
+        })
+
+        expect(mockOnChange).toHaveBeenCalledWith('1234567890')
+    })
+
+    it('should handle errors correctly', () => {
+        const mockFormWithErrors = {
+            ...mockForm,
+            formState: {
+                errors: {
+                    firstName: {message: 'First name is required'},
+                    address1: {message: 'Address is required'}
+                }
+            }
+        }
+
+        const {result} = renderHook(() => useAddressFields({form: mockFormWithErrors}))
+
+        expect(result.current.firstName.error).toEqual({message: 'First name is required'})
+        expect(result.current.address1.error).toEqual({message: 'Address is required'})
+    })
+
+    it('should call useAutocompleteSuggestions with correct parameters', () => {
+        mockWatch.mockReturnValue('US')
+
+        renderHook(() => useAddressFields({form: mockForm}))
+
+        expect(useAutocompleteSuggestions).toHaveBeenCalledWith('', 'US')
+    })
+
+    it('should call useAutocompleteSuggestions with prefix when provided', () => {
+        mockWatch.mockReturnValue('CA')
+
+        renderHook(() => useAddressFields({form: mockForm, prefix: 'shipping'}))
+
+        expect(useAutocompleteSuggestions).toHaveBeenCalledWith('', 'CA')
+    })
+})

package/app/hooks/useAutocompleteSuggestions.js

@@ -0,0 +1,131 @@
+/*
+ * 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 {useState, useRef, useCallback, useEffect} from 'react'
+import {useMapsLibrary} from '@vis.gl/react-google-maps'
+import {convertGoogleMapsSuggestions} from '@salesforce/retail-react-app/app/utils/address-suggestions'
+
+const DEBOUNCE_DELAY = 300
+
+/**
+ * Custom hook for Google Maps Places autocomplete suggestions
+ * @param {string} inputString - The input string to search for
+ * @param {string} countryCode - Country code to filter results (e.g., 'US', 'CA')
+ * @param {Object} requestOptions - Additional request options for the API
+ * @returns {Object} Object containing suggestions, loading state, and reset function
+ */
+export const useAutocompleteSuggestions = (
+    inputString = '',
+    countryCode = '',
+    requestOptions = {}
+) => {
+    const places = useMapsLibrary('places')
+
+    const sessionTokenRef = useRef(null)
+    const debounceTimeoutRef = useRef(null)
+
+    const cacheRef = useRef(new Map())
+
+    const [suggestions, setSuggestions] = useState([])
+    const [isLoading, setIsLoading] = useState(false)
+
+    // Key format: `${inputString.toLowerCase().trim()}_${countryCode}`
+    const getCacheKey = useCallback((input, country) => {
+        return `${input.toLowerCase().trim()}_${country || ''}`
+    }, [])
+
+    const fetchSuggestions = useCallback(
+        async (input) => {
+            if (!places || !input || input.length < 3) {
+                setSuggestions([])
+                return
+            }
+
+            const cacheKey = getCacheKey(input, countryCode)
+
+            // Check cache first
+            if (cacheRef.current.has(cacheKey)) {
+                const cachedSuggestions = cacheRef.current.get(cacheKey)
+                setSuggestions(cachedSuggestions)
+                setIsLoading(false)
+                return
+            }
+
+            setIsLoading(true)
+
+            try {
+                const {AutocompleteSessionToken, AutocompleteSuggestion} = places
+
+                if (!sessionTokenRef.current) {
+                    sessionTokenRef.current = new AutocompleteSessionToken()
+                }
+
+                const request = {
+                    ...requestOptions,
+                    input: input,
+                    includedPrimaryTypes: ['street_address'],
+                    sessionToken: sessionTokenRef.current
+                }
+
+                if (countryCode) {
+                    request.includedRegionCodes = [countryCode]
+                }
+
+                const response = await AutocompleteSuggestion.fetchAutocompleteSuggestions(request)
+
+                const googleSuggestions = convertGoogleMapsSuggestions(response.suggestions)
+
+                // Store in cache for future use
+                cacheRef.current.set(cacheKey, googleSuggestions)
+
+                setSuggestions(googleSuggestions)
+            } catch (error) {
+                setSuggestions([])
+            } finally {
+                setIsLoading(false)
+            }
+        },
+        [places, countryCode, getCacheKey]
+    )
+
+    const resetSession = useCallback(() => {
+        sessionTokenRef.current = null
+        setSuggestions([])
+        setIsLoading(false)
+        if (debounceTimeoutRef.current) {
+            clearTimeout(debounceTimeoutRef.current)
+        }
+    }, [])
+
+    useEffect(() => {
+        if (debounceTimeoutRef.current) {
+            clearTimeout(debounceTimeoutRef.current)
+        }
+
+        if (!inputString || inputString.length < 3) {
+            setSuggestions([])
+            return
+        }
+
+        debounceTimeoutRef.current = setTimeout(() => {
+            fetchSuggestions(inputString)
+        }, DEBOUNCE_DELAY)
+
+        return () => {
+            if (debounceTimeoutRef.current) {
+                clearTimeout(debounceTimeoutRef.current)
+            }
+        }
+    }, [inputString, fetchSuggestions])
+
+    return {
+        suggestions,
+        isLoading,
+        resetSession,
+        fetchSuggestions
+    }
+}