@salesforce/retail-react-app 1.0.0-preview.0

package/app/components/product-item/index.jsx

@@ -0,0 +1,146 @@
+/*
+ * Copyright (c) 2021, 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 PropTypes from 'prop-types'
+import {FormattedMessage} from 'react-intl'
+
+// Chakra Components
+import {Box, Fade, Flex, Stack, Text} from '@chakra-ui/react'
+
+// Project Components
+import {HideOnDesktop, HideOnMobile} from '@salesforce/retail-react-app/app/components/responsive'
+import ItemVariantProvider from '@salesforce/retail-react-app/app/components/item-variant'
+import CartItemVariantImage from '@salesforce/retail-react-app/app/components/item-variant/item-image'
+import CartItemVariantName from '@salesforce/retail-react-app/app/components/item-variant/item-name'
+import CartItemVariantAttributes from '@salesforce/retail-react-app/app/components/item-variant/item-attributes'
+import CartItemVariantPrice from '@salesforce/retail-react-app/app/components/item-variant/item-price'
+import LoadingSpinner from '@salesforce/retail-react-app/app/components/loading-spinner'
+import QuantityPicker from '@salesforce/retail-react-app/app/components/quantity-picker'
+
+// Utilities
+import {noop} from '@salesforce/retail-react-app/app/utils/utils'
+
+// Hooks
+import {useDerivedProduct} from '@salesforce/retail-react-app/app/hooks'
+
+/**
+ * Component representing a product item usually in a list with details about the product - name, variant, pricing, etc.
+ * @param {Object} product Product to be represented in the list item.
+ * @param {node} primaryAction Child component representing the most prominent action to be performed by the user.
+ * @param {node} secondaryActions Child component representing the other actions relevant to the product to be performed by the user.
+ * @param {func} onItemQuantityChange callback function to be invoked whenever item quantity changes.
+ * @param {boolean} showLoading Renders a loading spinner with overlay if set to true.
+ * @returns A JSX element representing product item in a list (eg: wishlist, cart, etc).
+ */
+const ProductItem = ({
+    product,
+    primaryAction,
+    secondaryActions,
+    onItemQuantityChange = noop,
+    showLoading = false
+}) => {
+    const {stepQuantity, showInventoryMessage, inventoryMessage, quantity, setQuantity} =
+        useDerivedProduct(product)
+    return (
+        <Box position="relative" data-testid={`sf-cart-item-${product.productId}`}>
+            <ItemVariantProvider variant={product}>
+                {showLoading && <LoadingSpinner />}
+                <Stack layerStyle="cardBordered" align="flex-start">
+                    <Flex width="full" alignItems="flex-start" backgroundColor="white">
+                        <CartItemVariantImage width={['88px', '136px']} mr={4} />
+                        <Stack spacing={3} flex={1}>
+                            <Stack spacing={1}>
+                                <CartItemVariantName />
+                                <CartItemVariantAttributes />
+                                <HideOnDesktop>
+                                    <Box marginTop={2}>
+                                        <CartItemVariantPrice align="left" />
+                                    </Box>
+                                </HideOnDesktop>
+                            </Stack>
+
+                            <Flex align="flex-end" justify="space-between">
+                                <Stack spacing={1}>
+                                    <Text fontSize="sm" color="gray.700">
+                                        <FormattedMessage
+                                            defaultMessage="Quantity:"
+                                            id="product_item.label.quantity"
+                                        />
+                                    </Text>
+                                    <QuantityPicker
+                                        step={stepQuantity}
+                                        value={quantity}
+                                        min={0}
+                                        clampValueOnBlur={false}
+                                        onBlur={(e) => {
+                                            // Default to last known quantity if a user leaves the box with an invalid value
+                                            const {value} = e.target
+
+                                            if (!value) {
+                                                setQuantity(product.quantity)
+                                            }
+                                        }}
+                                        onChange={(stringValue, numberValue) => {
+                                            // Set the Quantity of product to value of input if value number
+                                            if (numberValue >= 0) {
+                                                // Call handler
+                                                onItemQuantityChange(numberValue).then(
+                                                    (isValidChange) =>
+                                                        isValidChange && setQuantity(numberValue)
+                                                )
+                                            } else if (stringValue === '') {
+                                                // We want to allow the use to clear the input to start a new input so here we set the quantity to '' so NAN is not displayed
+                                                // User will not be able to add '' qauntity to the cart due to the add to cart button enablement rules
+                                                setQuantity(stringValue)
+                                            }
+                                        }}
+                                    />
+                                </Stack>
+                                <Stack>
+                                    <HideOnMobile>
+                                        <CartItemVariantPrice />
+                                    </HideOnMobile>
+                                    <Box display={['none', 'block', 'block', 'block']}>
+                                        {primaryAction}
+                                    </Box>
+                                </Stack>
+                            </Flex>
+
+                            <Box>
+                                {product && showInventoryMessage && (
+                                    <Fade in={true}>
+                                        <Text color="orange.600" fontWeight={600}>
+                                            {inventoryMessage}
+                                        </Text>
+                                    </Fade>
+                                )}
+                            </Box>
+
+                            {secondaryActions}
+                        </Stack>
+                    </Flex>
+
+                    <Box display={['block', 'none', 'none', 'none']} w={'full'}>
+                        {primaryAction}
+                    </Box>
+                </Stack>
+            </ItemVariantProvider>
+        </Box>
+    )
+}
+
+ProductItem.propTypes = {
+    product: PropTypes.object,
+    onItemQuantityChange: PropTypes.func,
+    onAddItemToCart: PropTypes.func,
+    showLoading: PropTypes.bool,
+    isWishlistItem: PropTypes.bool,
+    primaryAction: PropTypes.node,
+    secondaryActions: PropTypes.node
+}
+
+export default ProductItem

package/app/components/product-item/index.test.js

@@ -0,0 +1,38 @@
+/*
+ * Copyright (c) 2021, 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 ProductItem from '@salesforce/retail-react-app/app/components/product-item/index'
+import {mockedCustomerProductListsDetails} from '@salesforce/retail-react-app/app/mocks/mock-data'
+import {renderWithProviders} from '@salesforce/retail-react-app/app/utils/test-utils'
+import {screen} from '@testing-library/react'
+
+jest.mock('@salesforce/commerce-sdk-react', () => {
+    const originalModule = jest.requireActual('@salesforce/commerce-sdk-react')
+    return {
+        ...originalModule,
+        useCustomerBaskets: jest.fn().mockReturnValue({data: {baskets: [{currency: 'GBP'}]}})
+    }
+})
+
+// Set up and clean up
+beforeEach(() => {
+    jest.resetModules()
+})
+
+jest.setTimeout(60000)
+const MockedComponent = () => {
+    const product = mockedCustomerProductListsDetails.data[0]
+    return <ProductItem product={{...product, productName: product.name}} />
+}
+
+test('renders product item name, attributes and price', async () => {
+    renderWithProviders(<MockedComponent />)
+
+    expect(await screen.getByText(/apple ipod nano/i)).toBeInTheDocument()
+    expect(await screen.getByText(/color: green/i)).toBeInTheDocument()
+    expect(await screen.getByText(/memory size: 16 GB/i)).toBeInTheDocument()
+})

package/app/components/product-scroller/index.jsx

@@ -0,0 +1,172 @@
+/*
+ * Copyright (c) 2021, 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, {forwardRef, useRef} from 'react'
+import PropTypes from 'prop-types'
+import {AspectRatio, Box, Heading, IconButton, Skeleton, Stack} from '@chakra-ui/react'
+import ProductTile from '@salesforce/retail-react-app/app/components/product-tile'
+import {ChevronLeftIcon, ChevronRightIcon} from '@salesforce/retail-react-app/app/components/icons'
+
+/**
+ * Renders a scrollable, horizontal container of products with native scroll
+ * snapping and manual button controls.
+ */
+const ProductScroller = forwardRef(
+    (
+        {
+            header,
+            title,
+            products,
+            isLoading,
+            scrollProps,
+            itemWidth = {base: '70%', md: '40%', lg: 'calc(33.33% - 10px)'},
+            productTileProps,
+            ...props
+        },
+        ref
+    ) => {
+        const scrollRef = useRef()
+
+        // Renders nothing if we aren't loading and have no products.
+        if ((!products || products.length < 1) && !isLoading) {
+            return null
+        }
+
+        // Scroll the container left or right by 100%. Passing no args or `1`
+        // scrolls to the right, and passing `-1` scrolls left.
+        const scroll = (direction = 1) => {
+            scrollRef.current?.scrollBy({
+                top: 0,
+                left: direction * window.innerWidth,
+                behavior: 'smooth'
+            })
+        }
+
+        return (
+            <Box position="relative" data-testid="product-scroller" ref={ref}>
+                <Stack spacing={6} {...props}>
+                    {isLoading && <Skeleton height={6} width="150px" m="auto" />}
+
+                    {title && !header && !isLoading && (
+                        <Heading as="h2" fontSize="xl" textAlign="center">
+                            {title}
+                        </Heading>
+                    )}
+
+                    {!title && !isLoading && header}
+
+                    <Stack
+                        ref={scrollRef}
+                        direction="row"
+                        spacing={4}
+                        wrap="nowrap"
+                        overflowX="scroll"
+                        px={{base: 4, md: 8, lg: 0}}
+                        {...scrollProps}
+                        sx={{
+                            scrollPadding: {base: 16, md: 32, lg: 0},
+                            scrollSnapType: 'x mandatory',
+                            WebkitOverflowScrolling: 'touch', // Safari touch scrolling needed for scroll snap
+                            ...scrollProps?.sx
+                        }}
+                    >
+                        {(isLoading ? [0, 1, 2, 4] : products).map((product, idx) => {
+                            return (
+                                <Box
+                                    key={product?.id || idx}
+                                    flex="0 0 auto"
+                                    width={itemWidth}
+                                    style={{scrollSnapAlign: 'start'}}
+                                >
+                                    {isLoading ? (
+                                        <Stack data-testid="product-scroller-item-skeleton">
+                                            <AspectRatio ratio={1}>
+                                                <Skeleton />
+                                            </AspectRatio>
+                                            <Stack spacing={2}>
+                                                <Skeleton width="150px" height={5} />
+                                                <Skeleton width="75px" height={5} />
+                                            </Stack>
+                                        </Stack>
+                                    ) : (
+                                        <ProductTile
+                                            data-testid="product-scroller-item"
+                                            product={product}
+                                            {...(typeof productTileProps === 'function'
+                                                ? {...productTileProps(product)}
+                                                : {...productTileProps})}
+                                            dynamicImageProps={{
+                                                widths: ['70vw', '70vw', '40vw', '30vw']
+                                            }}
+                                        />
+                                    )}
+                                </Box>
+                            )
+                        })}
+                    </Stack>
+                </Stack>
+
+                {products?.length > 3 && (
+                    <>
+                        <Box
+                            display={{
+                                base: 'none',
+                                lg: 'block'
+                            }}
+                            position="absolute"
+                            top="50%"
+                            left={{base: 0, lg: 4}}
+                            transform="translateY(-50%)"
+                        >
+                            <IconButton
+                                data-testid="product-scroller-nav-left"
+                                aria-label="Scroll products left"
+                                icon={<ChevronLeftIcon color="black" />}
+                                borderRadius="full"
+                                colorScheme="whiteAlpha"
+                                onClick={() => scroll(-1)}
+                            />
+                        </Box>
+
+                        <Box
+                            display={{
+                                base: 'none',
+                                lg: 'block'
+                            }}
+                            position="absolute"
+                            top="50%"
+                            right={{base: 0, lg: 4}}
+                            transform="translateY(-50%)"
+                        >
+                            <IconButton
+                                data-testid="product-scroller-nav-right"
+                                aria-label="Scroll products right"
+                                icon={<ChevronRightIcon color="black" />}
+                                borderRadius="full"
+                                colorScheme="whiteAlpha"
+                                onClick={() => scroll(1)}
+                            />
+                        </Box>
+                    </>
+                )}
+            </Box>
+        )
+    }
+)
+
+ProductScroller.displayName = 'ProductScroller'
+
+ProductScroller.propTypes = {
+    header: PropTypes.any,
+    title: PropTypes.any,
+    products: PropTypes.array,
+    isLoading: PropTypes.bool,
+    scrollProps: PropTypes.object,
+    itemWidth: PropTypes.oneOfType([PropTypes.string, PropTypes.number, PropTypes.object]),
+    productTileProps: PropTypes.oneOfType([PropTypes.func, PropTypes.object])
+}
+
+export default ProductScroller

package/app/components/product-scroller/index.test.js

@@ -0,0 +1,98 @@
+/*
+ * Copyright (c) 2021, 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 {screen} from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import ProductScroller from '@salesforce/retail-react-app/app/components/product-scroller/index'
+import {renderWithProviders} from '@salesforce/retail-react-app/app/utils/test-utils'
+
+// Our component uses `scrollBy` on an html element, which we need
+// to create ourselves as its not in jsdom by default. Here we make
+// it a spy so we can assert it was called when we expect.
+window.HTMLElement.prototype.scrollBy = jest.fn()
+
+const testProducts = [1, 2, 3, 4].map((i) => ({
+    id: i,
+    productId: `${i}`,
+    productName: `Product ${i}`,
+    image: {disBaseLink: '/testimage'},
+    price: 9.99,
+    currency: 'USD'
+}))
+
+describe('Product Scroller', () => {
+    test('renders loading skeletons', () => {
+        renderWithProviders(<ProductScroller isLoading />)
+        expect(screen.getAllByTestId('product-scroller-item-skeleton')).toHaveLength(4)
+    })
+    test('renders nothing when no products and not loading', () => {
+        renderWithProviders(<ProductScroller products={undefined} />)
+        expect(screen.queryByTestId('product-scroller')).not.toBeInTheDocument()
+    })
+    test('Renders product items', () => {
+        renderWithProviders(<ProductScroller title="Scroller Title" products={testProducts} />)
+        expect(screen.getByText('Scroller Title')).toBeInTheDocument()
+        expect(screen.getAllByTestId('product-scroller-item')).toHaveLength(4)
+    })
+    test('Renders scrollable product tiles with custom header component', () => {
+        renderWithProviders(
+            <ProductScroller
+                header={<h1 data-testid="custom-header">Scroller Header</h1>}
+                products={testProducts}
+            />
+        )
+        expect(screen.getByTestId('custom-header')).toBeInTheDocument()
+    })
+    test('Renders left/right scroll buttons', async () => {
+        const user = userEvent.setup()
+        renderWithProviders(<ProductScroller title="Scroller Title" products={testProducts} />)
+        await user.click(screen.getByTestId('product-scroller-nav-right'))
+        expect(window.HTMLElement.prototype.scrollBy).toHaveBeenCalledWith({
+            top: 0,
+            left: 1024,
+            behavior: 'smooth'
+        })
+        await user.click(screen.getByTestId('product-scroller-nav-left'))
+        expect(window.HTMLElement.prototype.scrollBy).toHaveBeenCalledWith({
+            top: 0,
+            left: -1024,
+            behavior: 'smooth'
+        })
+        expect(screen.getByTestId('product-scroller-nav-left')).toBeInTheDocument()
+        expect(screen.getByTestId('product-scroller-nav-right')).toBeInTheDocument()
+    })
+    test('Does not render left/right scroll buttons when less than 4 products', () => {
+        renderWithProviders(
+            <ProductScroller title="Scroller Title" products={testProducts.slice(0, 2)} />
+        )
+        expect(screen.queryByTestId('product-scroller-nav-left')).not.toBeInTheDocument()
+        expect(screen.queryByTestId('product-scroller-nav-right')).not.toBeInTheDocument()
+    })
+    test('productTileProps as object', async () => {
+        const user = userEvent.setup()
+
+        const onClickMock = jest.fn()
+        renderWithProviders(
+            <ProductScroller products={testProducts} productTileProps={{onClick: onClickMock}} />
+        )
+        await user.click(screen.getByText(testProducts[0].productName))
+        expect(onClickMock).toHaveBeenCalled()
+    })
+    test('productTileProps as function', async () => {
+        const user = userEvent.setup()
+
+        const onClickMock = jest.fn()
+        renderWithProviders(
+            <ProductScroller
+                products={testProducts}
+                productTileProps={() => ({onClick: onClickMock})}
+            />
+        )
+        await user.click(screen.getByText(testProducts[0].productName))
+        expect(onClickMock).toHaveBeenCalled()
+    })
+})

package/app/components/product-tile/index.jsx

@@ -0,0 +1,195 @@
+/*
+ * Copyright (c) 2022, 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 React, {useState} from 'react'
+import PropTypes from 'prop-types'
+import {HeartIcon, HeartSolidIcon} from '@salesforce/retail-react-app/app/components/icons'
+
+// Components
+import {
+    AspectRatio,
+    Box,
+    Skeleton as ChakraSkeleton,
+    Text,
+    Stack,
+    useMultiStyleConfig,
+    IconButton
+} from '@chakra-ui/react'
+import DynamicImage from '@salesforce/retail-react-app/app/components/dynamic-image'
+
+// Hooks
+import {useIntl} from 'react-intl'
+
+// Other
+import {productUrlBuilder} from '@salesforce/retail-react-app/app/utils/url'
+import Link from '@salesforce/retail-react-app/app/components/link'
+import withRegistration from '@salesforce/retail-react-app/app/components/with-registration'
+import {useCurrency} from '@salesforce/retail-react-app/app/hooks'
+
+const IconButtonWithRegistration = withRegistration(IconButton)
+
+// Component Skeleton
+export const Skeleton = () => {
+    const styles = useMultiStyleConfig('ProductTile')
+    return (
+        <Box data-testid="sf-product-tile-skeleton">
+            <Stack spacing={2}>
+                <Box {...styles.imageWrapper}>
+                    <AspectRatio ratio={1} {...styles.image}>
+                        <ChakraSkeleton />
+                    </AspectRatio>
+                </Box>
+                <ChakraSkeleton width="80px" height="20px" />
+                <ChakraSkeleton width={{base: '120px', md: '220px'}} height="12px" />
+            </Stack>
+        </Box>
+    )
+}
+
+/**
+ * The ProductTile is a simple visual representation of a
+ * product object. It will show it's default image, name and price.
+ * It also supports favourite products, controlled by a heart icon.
+ */
+const ProductTile = (props) => {
+    const intl = useIntl()
+    const {
+        product,
+        enableFavourite = false,
+        isFavourite,
+        onFavouriteToggle,
+        dynamicImageProps,
+        ...rest
+    } = props
+
+    const {currency, image, price, productId, hitType} = product
+
+    // ProductTile is used by two components, RecommendedProducts and ProductList.
+    // RecommendedProducts provides a localized product name as `name` and non-localized product
+    // name as `productName`. ProductList provides a localized name as `productName` and does not
+    // use the `name` property.
+    const localizedProductName = product.name ?? product.productName
+
+    const {currency: activeCurrency} = useCurrency()
+    const [isFavouriteLoading, setFavouriteLoading] = useState(false)
+    const styles = useMultiStyleConfig('ProductTile')
+
+    return (
+        <Link
+            data-testid="product-tile"
+            {...styles.container}
+            to={productUrlBuilder({id: productId}, intl.local)}
+            {...rest}
+        >
+            <Box {...styles.imageWrapper}>
+                {image && (
+                    <AspectRatio {...styles.image}>
+                        <DynamicImage
+                            src={`${image.disBaseLink || image.link}[?sw={width}&q=60]`}
+                            widths={dynamicImageProps?.widths}
+                            imageProps={{
+                                alt: image.alt,
+                                ...dynamicImageProps?.imageProps
+                            }}
+                        />
+                    </AspectRatio>
+                )}
+
+                {enableFavourite && (
+                    <Box
+                        onClick={(e) => {
+                            // stop click event from bubbling
+                            // to avoid user from clicking the underlying
+                            // product while the favourite icon is disabled
+                            e.preventDefault()
+                        }}
+                    >
+                        <IconButtonWithRegistration
+                            aria-label={intl.formatMessage({
+                                id: 'product_tile.assistive_msg.wishlist',
+                                defaultMessage: 'Wishlist'
+                            })}
+                            icon={isFavourite ? <HeartSolidIcon /> : <HeartIcon />}
+                            {...styles.favIcon}
+                            disabled={isFavouriteLoading}
+                            onClick={async () => {
+                                setFavouriteLoading(true)
+                                await onFavouriteToggle(!isFavourite)
+                                setFavouriteLoading(false)
+                            }}
+                        />
+                    </Box>
+                )}
+            </Box>
+
+            {/* Title */}
+            <Text {...styles.title}>{localizedProductName}</Text>
+
+            {/* Price */}
+            <Text {...styles.price} data-testid="product-tile-price">
+                {hitType === 'set' &&
+                    intl.formatMessage({
+                        id: 'product_tile.label.starting_at_price',
+                        defaultMessage: 'Starting at'
+                    })}{' '}
+                {intl.formatNumber(price, {
+                    style: 'currency',
+                    currency: currency || activeCurrency
+                })}
+            </Text>
+        </Link>
+    )
+}
+
+ProductTile.displayName = 'ProductTile'
+
+ProductTile.propTypes = {
+    /**
+     * The product search hit that will be represented in this
+     * component.
+     */
+    product: PropTypes.shape({
+        currency: PropTypes.string,
+        image: PropTypes.shape({
+            alt: PropTypes.string,
+            disBaseLink: PropTypes.string,
+            link: PropTypes.string
+        }),
+        price: PropTypes.number,
+        // `name` is present and localized when `product` is provided by a RecommendedProducts component
+        // (from Shopper Products `getProducts` endpoint), but is not present when `product` is
+        // provided by a ProductList component.
+        // See: https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-products?meta=getProducts
+        name: PropTypes.string,
+        // `productName` is localized when provided by a ProductList component (from Shopper Search
+        // `productSearch` endpoint), but is NOT localized when provided by a RecommendedProducts
+        // component (from Einstein Recommendations `getRecommendations` endpoint).
+        // See: https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-search?meta=productSearch
+        // See: https://developer.salesforce.com/docs/commerce/einstein-api/references/einstein-api-quick-start-guide?meta=getRecommendations
+        // Note: useEinstein() transforms snake_case property names from the API response to camelCase
+        productName: PropTypes.string,
+        productId: PropTypes.string,
+        hitType: PropTypes.string
+    }),
+    /**
+     * Enable adding/removing product as a favourite.
+     * Use case: wishlist.
+     */
+    enableFavourite: PropTypes.bool,
+    /**
+     * Display the product as a faviourite.
+     */
+    isFavourite: PropTypes.bool,
+    /**
+     * Callback function to be invoked when the user
+     * interacts with favourite icon/button.
+     */
+    onFavouriteToggle: PropTypes.func,
+    dynamicImageProps: PropTypes.object
+}
+
+export default ProductTile