fix(ui): thread cache tag to list view thumbnails (#11741)

<!--

Thank you for the PR! Please go through the checklist below and make
sure you've completed all the steps.

Please review the
[CONTRIBUTING.md](https://github.com/payloadcms/payload/blob/main/CONTRIBUTING.md)
document in this repository if you haven't already.

The following items will ensure that your PR is handled as smoothly as
possible:

- PR Title must follow conventional commits format. For example, `feat:
my new feature`, `fix(plugin-seo): my fix`.
- Minimal description explained as if explained to someone not
immediately familiar with the code.
- Provide before/after screenshots or code diffs if applicable.
- Link any related issues/discussions from GitHub or Discord.
- Add review comments if necessary to explain to the reviewer the logic
behind a change

### What?

### Why?

### How?

Fixes #

-->
### What?
This PR threads a cache tag to the `Thumbnail` component through the
default `File` cell in the list view if cache tags are enabled in upload
config. These changes also adjust the `Thumbnail` component to use
`useMemo` instead of constructing a `src` later due to:

```
const img = new Image()
img.src = fileSrc
```

The above causes an extra request to be made if cache tags are enabled.

### Why?
To thread cache tags through to the list view thumbnails.

### How?
Changes the default `File` cell to pass the cache tag through if
enabled, and changing a failing test to accommodate cache tags in the
list view.

Addresses cache tag issue in #11690

---------

Co-authored-by: Paul Popus <paul@payloadcms.com>

Author: akhrarovsaid

packages/ui/src/elements/EditUpload/index.tsx

@@ -10,6 +10,7 @@ import 'react-image-crop/dist/ReactCrop.css'
 import { editDrawerSlug } from '../../elements/Upload/index.js'
 import { PlusIcon } from '../../icons/Plus/index.js'
 import { useTranslation } from '../../providers/Translation/index.js'
+import { appendCacheTag } from '../../utilities/appendCacheTag.js'
 import { Button } from '../Button/index.js'
 import './index.scss'
 
@@ -169,8 +170,7 @@ export const EditUpload: React.FC<EditUploadProps> = ({
     setFocalPosition({ x: xCenter, y: yCenter })
   }
 
-  const queryChar = fileSrc?.includes('?') ? '&' : '?'
-  const fileSrcToUse = imageCacheTag ? `${fileSrc}${queryChar}${encodeURIComponent(imageCacheTag)}` : fileSrc
+  const fileSrcToUse = fileSrc ? appendCacheTag(fileSrc, imageCacheTag) : fileSrc
 
   return (
     <div className={baseClass}>

packages/ui/src/elements/PreviewSizes/index.tsx

@@ -3,6 +3,7 @@ import type { Data, FileSize, SanitizedCollectionConfig, SanitizedUploadConfig }
 
 import React, { useEffect, useMemo, useState } from 'react'
 
+import { appendCacheTag } from '../../utilities/appendCacheTag.js'
 import { FileMeta } from '../FileDetails/FileMeta/index.js'
 import './index.scss'
 
@@ -99,8 +100,7 @@ export const PreviewSizes: React.FC<PreviewSizesProps> = ({ doc, imageCacheTag,
       return null
     }
     if (doc.url) {
-      const queryChar = doc.url.includes('?') ? '&' : '?'
-      return `${doc.url}${imageCacheTag ? `${queryChar}${encodeURIComponent(imageCacheTag)}` : ''}`
+      return appendCacheTag(doc.url, imageCacheTag)
     }
   }
   useEffect(() => {

packages/ui/src/elements/Table/DefaultCell/fields/File/index.tsx

@@ -43,6 +43,9 @@ export const FileCell: React.FC<FileCellProps> = ({
       })
     }
 
+    const uploadConfig = collectionConfig?.upload
+    const imageCacheTag = uploadConfig?.cacheTags && rowData?.updatedAt
+
     return (
       <div className={baseClass}>
         <Thumbnail
@@ -53,9 +56,9 @@ export const FileCell: React.FC<FileCellProps> = ({
             filename,
           }}
           fileSrc={fileSrc}
-          imageCacheTag={collectionConfig?.upload?.cacheTags && rowData?.updatedAt}
+          imageCacheTag={imageCacheTag}
           size="small"
-          uploadConfig={collectionConfig?.upload}
+          uploadConfig={uploadConfig}
         />
         <span className={`${baseClass}__filename`}>{String(filename)}</span>
       </div>

packages/ui/src/elements/Thumbnail/index.tsx

@@ -8,6 +8,7 @@ const baseClass = 'thumbnail'
 import type { SanitizedCollectionConfig } from 'payload'
 
 import { File } from '../../graphics/File/index.js'
+import { appendCacheTag } from '../../utilities/appendCacheTag.js'
 import { ShimmerEffect } from '../ShimmerEffect/index.js'
 
 export type ThumbnailProps = {
@@ -36,33 +37,27 @@ export const Thumbnail: React.FC<ThumbnailProps> = (props) => {
 
   const classNames = [baseClass, `${baseClass}--size-${size || 'medium'}`, className].join(' ')
 
+  const src = React.useMemo(
+    () => (fileSrc ? appendCacheTag(fileSrc, imageCacheTag) : null),
+    [fileSrc, imageCacheTag],
+  )
+
   React.useEffect(() => {
-    if (!fileSrc) {
+    if (!src) {
       setFileExists(false)
       return
     }
     setFileExists(undefined)
 
     const img = new Image()
-    img.src = fileSrc
+    img.src = src
     img.onload = () => {
       setFileExists(true)
     }
     img.onerror = () => {
       setFileExists(false)
     }
-  }, [fileSrc])
-
-  let src: null | string = null
-
-  /**
-   * If an imageCacheTag is provided, append it to the fileSrc
-   * Check if the fileSrc already has a query string, if it does, append the imageCacheTag with an ampersand
-   */
-  if (fileSrc) {
-    const queryChar = fileSrc?.includes('?') ? '&' : '?'
-    src = imageCacheTag ? `${fileSrc}${queryChar}${encodeURIComponent(imageCacheTag)}` : fileSrc
-  }
+  }, [src])
 
   return (
     <div className={classNames}>
@@ -87,33 +82,27 @@ export function ThumbnailComponent(props: ThumbnailComponentProps) {
 
   const classNames = [baseClass, `${baseClass}--size-${size || 'medium'}`, className].join(' ')
 
+  const src = React.useMemo(
+    () => (fileSrc ? appendCacheTag(fileSrc, imageCacheTag) : null),
+    [fileSrc, imageCacheTag],
+  )
+
   React.useEffect(() => {
-    if (!fileSrc) {
+    if (!src) {
       setFileExists(false)
       return
     }
     setFileExists(undefined)
 
     const img = new Image()
-    img.src = fileSrc
+    img.src = src
     img.onload = () => {
       setFileExists(true)
     }
     img.onerror = () => {
       setFileExists(false)
     }
-  }, [fileSrc])
-
-  let src: string = ''
-
-  /**
-   * If an imageCacheTag is provided, append it to the fileSrc
-   * Check if the fileSrc already has a query string, if it does, append the imageCacheTag with an ampersand
-   */
-  if (fileSrc) {
-    const queryChar = fileSrc?.includes('?') ? '&' : '?'
-    src = imageCacheTag ? `${fileSrc}${queryChar}${encodeURIComponent(imageCacheTag)}` : fileSrc
-  }
+  }, [src])
 
   return (
     <div className={classNames}>

packages/ui/src/utilities/appendCacheTag.spec.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest'
+
+import { appendCacheTag } from './appendCacheTag.js'
+
+describe('appendCacheTag', () => {
+  it('should return the url unchanged when cacheTag is undefined', () => {
+    expect(appendCacheTag('https://example.com/image.jpg', undefined)).toBe(
+      'https://example.com/image.jpg',
+    )
+  })
+
+  it('should return the url unchanged when cacheTag is false', () => {
+    expect(appendCacheTag('https://example.com/image.jpg', false)).toBe(
+      'https://example.com/image.jpg',
+    )
+  })
+
+  it('should return the url unchanged when cacheTag is empty string', () => {
+    expect(appendCacheTag('https://example.com/image.jpg', '')).toBe(
+      'https://example.com/image.jpg',
+    )
+  })
+
+  it('should append the cache tag with ? when the url has no query string', () => {
+    const result = appendCacheTag('https://example.com/image.jpg', '2024-01-01T00:00:00.000Z')
+    expect(result).toBe('https://example.com/image.jpg?2024-01-01T00%3A00%3A00.000Z')
+  })
+
+  it('should append the cache tag with & when the url already has a query string', () => {
+    const result = appendCacheTag(
+      'https://example.com/image.jpg?w=800&q=75',
+      '2024-01-01T00:00:00.000Z',
+    )
+    expect(result).toBe('https://example.com/image.jpg?w=800&q=75&2024-01-01T00%3A00%3A00.000Z')
+  })
+
+  it('should URI-encode the cache tag value', () => {
+    const result = appendCacheTag('/image.jpg', '2024-06-15T12:30:00.000Z')
+    expect(result).toBe('/image.jpg?2024-06-15T12%3A30%3A00.000Z')
+  })
+
+  it('should work with relative urls', () => {
+    const result = appendCacheTag('/uploads/photo.png', '2024-01-01T00:00:00.000Z')
+    expect(result).toBe('/uploads/photo.png?2024-01-01T00%3A00%3A00.000Z')
+  })
+
+  it('should work with relative urls that already have a query string', () => {
+    const result = appendCacheTag('/uploads/photo.png?size=large', '2024-01-01T00:00:00.000Z')
+    expect(result).toBe('/uploads/photo.png?size=large&2024-01-01T00%3A00%3A00.000Z')
+  })
+})

packages/ui/src/utilities/appendCacheTag.ts

@@ -0,0 +1,11 @@
+/**
+ * Appends a cache-busting tag to a URL as a query parameter.
+ * If the URL already has a query string, the tag is appended with `&`, otherwise with `?`.
+ */
+export function appendCacheTag(url: string, cacheTag: false | string | undefined): string {
+  if (!cacheTag) {
+    return url
+  }
+  const queryChar = url.includes('?') ? '&' : '?'
+  return `${url}${queryChar}${encodeURIComponent(cacheTag)}`
+}

test/uploads/e2e.spec.ts

@@ -69,6 +69,12 @@ const dirname = path.dirname(filename)
  */
 const cacheTagPattern = /\?\d{4}-\d{2}-\d{2}T\d{2}%3A\d{2}%3A\d{2}\.\d{3}Z/
 
+const adminThumbnailFunctionSrcPattern = new RegExp(
+  String.raw`^https://raw\.githubusercontent\.com/payloadcms/website/refs/heads/main/public/images/universal-truth\.jpg` +
+    cacheTagPattern.source +
+    '$',
+)
+
 const { afterAll, beforeAll, beforeEach, describe } = test
 
 let payload: PayloadTestSDK<Config>
@@ -681,10 +687,9 @@ describe('Uploads', () => {
 
     // Ensure sure false or null shows generic file svg
     const genericUploadImage = page.locator('tr.row-1 .thumbnail img')
-    await expect(genericUploadImage).toHaveAttribute(
-      'src',
-      /^https:\/\/raw\.githubusercontent\.com\/payloadcms\/website\/refs\/heads\/main\/public\/images\/universal-truth\.jpg(\?.*)?$/,
-    )
+
+    // cacheTags defaults to true, so the cache tag is appended to the src in list view
+    await expect(genericUploadImage).toHaveAttribute('src', adminThumbnailFunctionSrcPattern)
   })
 
   test('should render adminThumbnail when using a custom thumbnail URL with additional queries', async () => {
@@ -1969,10 +1974,7 @@ describe('Uploads', () => {
       await page.locator('#field-withAdminThumbnail button.upload__listToggler').click()
       await page.locator('tr.row-1 td.cell-filename button.default-cell__first-cell').click()
       const thumbnail = page.locator('#field-withAdminThumbnail div.thumbnail > img')
-      await expect(thumbnail).toHaveAttribute(
-        'src',
-        /^https:\/\/raw\.githubusercontent\.com\/payloadcms\/website\/refs\/heads\/main\/public\/images\/universal-truth\.jpg(\?.*)?$/,
-      )
+      await expect(thumbnail).toHaveAttribute('src', adminThumbnailFunctionSrcPattern)
     })
 
     test('should select an image within target range', async () => {