@salesforce/retail-react-app 7.0.0-preview.0 → 7.0.0

package/app/utils/image.test.js

@@ -6,7 +6,10 @@
  */
 /* eslint-disable jest/no-conditional-expect */
 import {version} from 'react'
-import {getImageAttributes} from '@salesforce/retail-react-app/app/utils/image'
+import {
+    getImageAttributes,
+    getImageLinkAttributes
+} from '@salesforce/retail-react-app/app/utils/image'
 
 const [majorStr] = version.split('.', 1)
 const major = parseInt(majorStr, 10)
@@ -124,3 +127,140 @@ describe('getImageAttributes()', () => {
         })
     })
 })
+
+describe('getImageLinkAttributes()', () => {
+    test('empty image properties', () => {
+        expect(getImageLinkAttributes({})).toBeUndefined()
+    })
+
+    test('image properties without fetch priority and loading strategy', () => {
+        expect(getImageLinkAttributes(imageProps)).toBeUndefined()
+    })
+
+    test('image properties with fetch priority, without loading strategy, sizes and srcSet', () => {
+        expect(getImageLinkAttributes({...imageProps, fetchPriority: 'high'})).toStrictEqual({
+            rel: 'preload',
+            as: 'image',
+            href: imageProps.src,
+            fetchPriority: 'high'
+        })
+    })
+
+    test('image properties with fetch priority, sizes and srcSet, without loading strategy', () => {
+        expect(
+            getImageLinkAttributes({
+                ...imageProps,
+                fetchPriority: 'high',
+                sizes: '100vw',
+                srcSet: `${imageProps.src} 240w`
+            })
+        ).toStrictEqual({
+            rel: 'preload',
+            as: 'image',
+            href: imageProps.src,
+            fetchPriority: 'high',
+            imageSizes: '100vw',
+            imageSrcSet: `${imageProps.src} 240w`
+        })
+    })
+
+    test('image properties with fetch priority, type and media, without loading strategy, sizes and srcSet', () => {
+        expect(
+            getImageLinkAttributes({
+                ...imageProps,
+                fetchPriority: 'high',
+                type: 'image/jpeg',
+                media: '(min-width: 80em)'
+            })
+        ).toStrictEqual({
+            rel: 'preload',
+            as: 'image',
+            href: imageProps.src,
+            fetchPriority: 'high',
+            type: 'image/jpeg',
+            media: '(min-width: 80em)'
+        })
+    })
+
+    test('image properties with fetch priority, type, media, sizes and srcSet, without loading strategy', () => {
+        expect(
+            getImageLinkAttributes({
+                ...imageProps,
+                fetchPriority: 'high',
+                type: 'image/jpeg',
+                media: '(min-width: 80em)',
+                sizes: '100vw',
+                srcSet: `${imageProps.src} 240w`
+            })
+        ).toStrictEqual({
+            rel: 'preload',
+            as: 'image',
+            href: imageProps.src,
+            fetchPriority: 'high',
+            type: 'image/jpeg',
+            media: '(min-width: 80em)',
+            imageSizes: '100vw',
+            imageSrcSet: `${imageProps.src} 240w`
+        })
+    })
+
+    describe('loading="eager"', () => {
+        test('image properties without fetch priority', () => {
+            expect(getImageLinkAttributes({...imageProps, loading: 'eager'})).toBeUndefined()
+        })
+
+        test('image properties with fetch priority, without loading strategy, sizes and srcSet', () => {
+            expect(
+                getImageLinkAttributes({...imageProps, loading: 'eager', fetchPriority: 'high'})
+            ).toStrictEqual({
+                rel: 'preload',
+                as: 'image',
+                href: imageProps.src,
+                fetchPriority: 'high'
+            })
+        })
+
+        test('image properties with fetch priority, sizes and srcSet', () => {
+            expect(
+                getImageLinkAttributes({
+                    ...imageProps,
+                    loading: 'eager',
+                    fetchPriority: 'high',
+                    sizes: '100vw',
+                    srcSet: `${imageProps.src} 240w`
+                })
+            ).toStrictEqual({
+                rel: 'preload',
+                as: 'image',
+                href: imageProps.src,
+                fetchPriority: 'high',
+                imageSizes: '100vw',
+                imageSrcSet: `${imageProps.src} 240w`
+            })
+        })
+    })
+
+    describe('loading="lazy"', () => {
+        test('image properties without fetch priority', () => {
+            expect(getImageLinkAttributes({...imageProps, loading: 'lazy'})).toBeUndefined()
+        })
+
+        test('image properties with fetch priority', () => {
+            expect(
+                getImageLinkAttributes({...imageProps, loading: 'lazy', fetchPriority: 'high'})
+            ).toBeUndefined()
+        })
+
+        test('image properties with fetch priority, sizes and srcSet', () => {
+            expect(
+                getImageLinkAttributes({
+                    ...imageProps,
+                    loading: 'eager',
+                    fetchPriority: 'lazy',
+                    sizes: '100vw',
+                    srcSet: `${imageProps.src} 240w`
+                })
+            ).toBeUndefined()
+        })
+    })
+})

package/app/utils/responsive-image.js

@@ -1,10 +1,9 @@
 /*
- * Copyright (c) 2021, salesforce.com, inc.
+ * 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 theme from '@salesforce/retail-react-app/app/components/shared/theme'
 import logger from '@salesforce/retail-react-app/app/utils/logger-instance'
 
@@ -17,119 +16,45 @@ const getBreakpointLabels = (breakpoints) =>
         .sort((a, b) => parseFloat(a[1]) - parseFloat(b[1]))
         .map(([key]) => key)
 
+const vwValue = /^\d+vw$/
+const pxValue = /^\d+px$/
+const emValue = /^\d+em$/
+
 const {breakpoints: defaultBreakpoints} = theme
 let themeBreakpoints = defaultBreakpoints
 let breakpointLabels = getBreakpointLabels(themeBreakpoints)
 
 /**
- * @param {Object} props
- * @param {string} props.src - Dynamic src having an optional param that can vary with widths. For example: `image[_{width}].jpg` or `image.jpg[?sw={width}&q=60]`
- * @param {(number[]|string[]|Object)} [props.widths] - Image widths relative to the breakpoints, whose units can either be px or vw or unit-less. They will be mapped to the corresponding `sizes` and `srcSet`.
- * @param {Object} [props.breakpoints] - The current theme's breakpoints. If not given, Chakra's default breakpoints will be used.
- * @return {Object} src, sizes, and srcSet props for your image component
+ * Helper to create very specific `media` attributes for responsive preload purposes.
+ * @param {number} breakpointIndex
+ * @return {({min?: string, max?: string} | undefined)}
+ * @see {@link https://web.dev/articles/preload-responsive-images#picture}
  */
-export const getResponsiveImageAttributes = ({src, widths, breakpoints = defaultBreakpoints}) => {
-    if (!widths) {
-        return {
-            src: getSrcWithoutOptionalParams(src)
+const obtainImageLinkMedia = (breakpointIndex) => {
+    const toMediaValue = (bp, type) => {
+        const val = themeBreakpoints[bp]
+        if (emValue.test(val)) {
+            // em value
+            const parsed = parseFloat(val)
+            return {[type]: type === 'max' ? `${parsed - 0.01}em` : `${parsed}em`}
         }
-    }
-
-    themeBreakpoints = breakpoints
-    breakpointLabels = getBreakpointLabels(themeBreakpoints)
 
-    // Order of these attributes matter! If src is not last, Safari will refetch images
-    // multiple times (once when it processes src and again when it processes sizes / srcSet)
-    // See https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2223
-    return {
-        sizes: mapWidthsToSizes(widths),
-        srcSet: mapWidthsToSrcSet(widths, src),
-        src: getSrcWithoutOptionalParams(src)
+        const parsed = parseInt(val, 10)
+        return {[type]: type === 'max' ? `${parsed - 1}px` : `${parsed}px`}
     }
-}
-
-/**
- * @param {(number[]|string[]|Object)} widths
- * @return {string}
- */
-const mapWidthsToSizes = (widths) => {
-    const _widths = withUnit(Array.isArray(widths) ? widths : widthsAsArray(widths))
 
-    return breakpointLabels
-        .slice(0, _widths.length)
-        .map((bp, i) => {
-            return i === 0 ? _widths[i] : `(min-width: ${themeBreakpoints[bp]}) ${_widths[i]}`
-        })
-        .reverse()
-        .join(', ')
-}
-
-/**
- * @param {(number[]|string[]|Object)} widths
- * @return {string}
- */
-const mapWidthsToSrcSet = (widths, dynamicSrc) => {
-    let _widths = isObject(widths) ? widthsAsArray(widths) : widths.slice(0)
-
-    if (_widths.length < breakpointLabels.length) {
-        const lastWidth = _widths[_widths.length - 1]
-        const amountToPad = breakpointLabels.length - _widths.length
-
-        _widths = [..._widths, ...Array(amountToPad).fill(lastWidth)]
+    const nextBp = breakpointLabels.at(breakpointIndex + 1)
+    const currentBp = breakpointLabels.at(breakpointIndex)
+    if (breakpointIndex === 0) {
+        // first
+        return toMediaValue(nextBp, 'max')
+    } else if (breakpointIndex === breakpointLabels.length - 1) {
+        // last
+        return toMediaValue(currentBp, 'min')
     }
-
-    _widths = uniqueArray(convertToPxNumbers(_widths)).sort()
-
-    const srcSet = []
-    _widths.forEach((width) => {
-        srcSet.push(width)
-        srcSet.push(width * 2) // for devices with higher pixel density
-    })
-
-    return srcSet.map((imageWidth) => `${getSrc(dynamicSrc, imageWidth)} ${imageWidth}w`).join(', ')
-}
-
-const vwValue = /^\d+vw$/
-const pxValue = /^\d+px$/
-
-/**
- * @param {string[]|number[]} widths
- * @return {number[]}
- */
-const convertToPxNumbers = (widths) => {
-    return widths
-        .map((width, i) => {
-            if (typeof width === 'number') {
-                return width
-            }
-
-            if (vwValue.test(width)) {
-                const vw = parseFloat(width)
-                const currentBp = breakpointLabels[i]
-                // We imagine the biggest image for the current breakpoint
-                // to be when the viewport is closely approaching the _next breakpoint_.
-                const nextBp = breakpointLabels[i + 1]
-
-                if (nextBp) {
-                    return vwToPx(vw, nextBp)
-                } else {
-                    // We're already at the last breakpoint
-                    return widths[i] !== widths[i - 1] ? vwToPx(vw, currentBp) : undefined
-                }
-            } else if (pxValue.test(width)) {
-                return parseInt(width)
-            } else {
-                logger.error('Expecting to see values with vw or px unit only', {
-                    namespace: 'utils.convertToPxNumbers'
-                })
-                return 0
-            }
-        })
-        .filter((width) => width !== undefined)
+    return {...toMediaValue(currentBp, 'min'), ...toMediaValue(nextBp, 'max')}
 }
 
-const uniqueArray = (array) => [...new Set(array)]
-
 /**
  * @param {(number[]|string[])} widths
  */
@@ -147,24 +72,28 @@ const isObject = (o) => o?.constructor === Object
  */
 const widthsAsArray = (widths) => {
     const biggestBreakpoint = breakpointLabels.filter((bp) => Boolean(widths[bp])).pop()
-
     let mostRecent
     return breakpointLabels.slice(0, breakpointLabels.indexOf(biggestBreakpoint) + 1).map((bp) => {
         if (widths[bp]) {
             mostRecent = widths[bp]
             return widths[bp]
-        } else {
-            return mostRecent
         }
+        return mostRecent
     })
 }
 
+/**
+ * @param {number} em
+ * @param {number} [browserDefaultFontSize]
+ */
+const emToPx = (em, browserDefaultFontSize = 16) => Math.round(em * browserDefaultFontSize)
+
 /**
  * @param {number} vw
  * @param {string} breakpoint
  */
 const vwToPx = (vw, breakpoint) => {
-    let result = (vw / 100) * parseFloat(themeBreakpoints[breakpoint])
+    const result = (vw / 100) * parseFloat(themeBreakpoints[breakpoint])
     const breakpointsDefinedInPx = Object.values(themeBreakpoints).some((val) => pxValue.test(val))
 
     // Assumes theme's breakpoints are defined in either em or px
@@ -172,12 +101,6 @@ const vwToPx = (vw, breakpoint) => {
     return breakpointsDefinedInPx ? result : emToPx(result)
 }
 
-/**
- * @param {number} em
- * @param {number} [browserDefaultFontSize]
- */
-const emToPx = (em, browserDefaultFontSize = 16) => Math.round(em * browserDefaultFontSize)
-
 /**
  * @param {string} dynamicSrc
  * @param {number} imageWidth
@@ -198,7 +121,166 @@ export const getSrc = (dynamicSrc, imageWidth) => {
  * // Returns 'https://example.com/image.jpg'
  * getSrcWithoutOptionalParams('https://example.com/image.jpg[?sw={width}]')
  */
-const getSrcWithoutOptionalParams = (dynamicSrc) => {
-    const optionalParams = /\[[^\]]+\]/g
-    return dynamicSrc.replace(optionalParams, '')
+const getSrcWithoutOptionalParams = (dynamicSrc) => dynamicSrc.replace(/\[[^\]]+\]/g, '')
+
+const padArray = (arr) => {
+    const l1 = arr.length
+    const l2 = breakpointLabels.length
+    if (l1 < l2) {
+        const lastEntry = arr.at(-1)
+        const amountToPad = l2 - l1
+        return [...arr, ...Array(amountToPad).fill(lastEntry)]
+    }
+    return arr
+}
+
+/**
+ * @param {string[]|number[]} widths
+ * @return {number[]}
+ */
+const convertToPxNumbers = (widths) =>
+    widths
+        .map((width, i) => {
+            if (typeof width === 'number') {
+                return width
+            }
+
+            if (vwValue.test(width)) {
+                const vw = parseFloat(width)
+                const currentBp = breakpointLabels[i]
+                // We imagine the biggest image for the current breakpoint
+                // to be when the viewport is closely approaching the _next breakpoint_.
+                const nextBp = breakpointLabels[i + 1]
+
+                if (nextBp) {
+                    return vwToPx(vw, nextBp)
+                }
+                // We're already at the last breakpoint
+                return widths[i] !== widths[i - 1] ? vwToPx(vw, currentBp) : undefined
+            } else if (pxValue.test(width)) {
+                return parseInt(width, 10)
+            } else {
+                logger.error('Expecting to see values with vw or px unit only', {
+                    namespace: 'utils.convertToPxNumbers'
+                })
+                return 0
+            }
+        })
+        .filter((width) => width !== undefined)
+
+/**
+ * Transforms an array of preload link objects by converting the raw `media`
+ * property of each entry (with `min` and/or `max` values) into actual media
+ * queries using `(min-width)` and/or `(max-width)`.
+ * @param {{srcSet: string, sizes: string, media: {min?: string, max?: string}}[]} links
+ * @return {{srcSet: string, sizes: string, media: string}[]}
+ */
+const convertImageLinksMedia = (links) =>
+    links.map((link) => {
+        const {
+            media: {min, max}
+        } = link
+        const acc = []
+        if (min) {
+            acc.push(`(min-width: ${min})`)
+        }
+        if (max) {
+            acc.push(`(max-width: ${max})`)
+        }
+        return {...link, media: acc.join(' and ')}
+    })
+
+/**
+ * Determines the data required for the responsive `<source>` and `<link rel="preload">
+ * portions/elements.
+ * @param {string} src
+ * @param {(number[]|string[])} widths
+ * @returns {{sources: {srcSet: string, sizes: string, media: string}[], links: {srcSet: string, sizes: string, media: string}[]}}
+ */
+const getResponsiveSourcesAndLinks = (src, widths) => {
+    const sizesWidths = withUnit(widths)
+    const l = sizesWidths.length
+    const _sizes = breakpointLabels.map((bp, i) => {
+        return i === 0
+            ? {
+                  media: undefined,
+                  mediaLink: obtainImageLinkMedia(i),
+                  sizes: sizesWidths[i]
+              }
+            : {
+                  media: `(min-width: ${themeBreakpoints[bp]})`,
+                  mediaLink: obtainImageLinkMedia(i),
+                  sizes: sizesWidths.at(i >= l ? l - 1 : i)
+              }
+    })
+
+    const sourcesWidths = convertToPxNumbers(padArray(widths))
+    const sourcesLength = sourcesWidths.length
+    const {sources, links} = breakpointLabels.reduce(
+        (acc, bp, idx) => {
+            // To support higher-density devices, request all images in 1x and 2x widths
+            const width = sourcesWidths.at(idx >= sourcesLength ? sourcesLength - 1 : idx)
+            const {sizes, media, mediaLink} = _sizes.at(idx)
+            const lastSource = acc.sources.at(-1)
+            const lastLink = acc.links.at(-1)
+            const srcSet = [1, 2]
+                .map((factor) => {
+                    const effectiveWidth = Math.round(width * factor)
+                    const effectiveSize = Math.round(width * factor)
+                    return `${getSrc(src, effectiveSize)} ${effectiveWidth}w`
+                })
+                .join(', ')
+
+            if (
+                idx < sourcesLength &&
+                (lastSource?.sizes !== sizes || srcSet !== lastSource?.srcSet)
+            ) {
+                // Only store new `<source>` if we haven't already stored those values
+                acc.sources.push({srcSet, sizes, media})
+            }
+
+            if (lastLink?.sizes !== sizes || srcSet !== lastLink?.srcSet) {
+                // Only store new `<link>` if we haven't already stored those values
+                acc.links.push({srcSet, sizes, media: mediaLink})
+            } else {
+                // If we have already stored those values, update the `max` portion of the related `<link>` data
+                lastLink.media.max = mediaLink.max
+            }
+            return acc
+        },
+        {sources: [], links: []}
+    )
+    return {sources: sources.reverse(), links: convertImageLinksMedia(links)}
+}
+
+/**
+ * Resolve the attributes required to create a DIS-optimized `<picture>` component.
+ * @param {Object} props
+ * @param {string} props.src - Dynamic src having an optional param that can vary with widths. For example: `image[_{width}].jpg` or `image.jpg[?sw={width}&q=60]`
+ * @param {(number[] |string[] |Object)} [props.widths] - Image widths relative to the breakpoints, whose units can either be px or vw or unit-less. They will be mapped to the corresponding `sizes` and `srcSet`.
+ * @param {Object} [props.breakpoints] - The current theme's breakpoints. If not given, Chakra's default breakpoints will be used.
+ * @return {Object} src, sizes, srcSet, media props for your image component
+ * @see {@link DynamicImage}
+ */
+export const getResponsivePictureAttributes = ({src, widths, breakpoints = defaultBreakpoints}) => {
+    if (!widths) {
+        return {
+            sources: [],
+            links: [],
+            src: getSrcWithoutOptionalParams(src)
+        }
+    }
+
+    if (breakpoints !== themeBreakpoints) {
+        themeBreakpoints = breakpoints
+        breakpointLabels = getBreakpointLabels(themeBreakpoints)
+    }
+
+    const _widths = isObject(widths) ? widthsAsArray(widths) : widths.slice(0)
+    const {sources, links} = getResponsiveSourcesAndLinks(src, _widths)
+    return {
+        sources,
+        links,
+        src: getSrcWithoutOptionalParams(src)
+    }
 }