feat: join field on upload fields (#8379)

This PR makes it possible to use the new `join` field in connection with
an `upload` field. Previously `join` was reserved only for
relationships.

Author: DanRibbens

docs/fields/join.mdx

@@ -6,8 +6,8 @@ desc: The Join field provides the ability to work on related documents. Learn ho
 keywords: join, relationship, junction, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs
 ---
 
-The Join Field is used to make Relationship fields in the opposite direction. It is used to show the relationship from
-the other side. The field itself acts as a virtual field, in that no new data is stored on the collection with a Join
+The Join Field is used to make Relationship and Upload fields available in the opposite direction. With a Join you can edit and view collections
+having reference to a specific collection document. The field itself acts as a virtual field, in that no new data is stored on the collection with a Join
 field. Instead, the Admin UI surfaces the related documents for a better editing experience and is surfaced by Payload's
 APIs.
 
@@ -16,6 +16,7 @@ The Join field is useful in scenarios including:
 - To surface `Order`s for a given `Product`
 - To view and edit `Posts` belonging to a `Category`
 - To work with any bi-directional relationship data
+- Displaying where a document or upload is used in other documents
 
 <LightDarkImage
   srcLight="https://payloadcms.com/images/docs/fields/join.png"
@@ -24,8 +25,8 @@ The Join field is useful in scenarios including:
   caption="Admin Panel screenshot of Join field"
 />
 
-For the Join field to work, you must have an existing [relationship](./relationship) field in the collection you are
-joining. This will reference the collection and path of the field of the related documents.
+For the Join field to work, you must have an existing [relationship](./relationship) or [upload](./upload) field in the
+collection you are joining. This will reference the collection and path of the field of the related documents.
 To add a Relationship Field, set the `type` to `join` in your [Field Config](./overview):
 
 ```ts
@@ -122,7 +123,7 @@ complete control over any type of relational architecture in Payload, all wrappe
 |------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | **`name`** \*          | To be used as the property name when retrieved from the database. [More](/docs/fields/overview#field-names)                                                                                   |
 | **`collection`** \*    | The `slug`s having the relationship field.                                                                                                                                                    |
-| **`on`** \*            | The relationship field name of the field that relates to collection document. Use dot notation for nested paths, like 'myGroup.relationName'.                                                 |
+| **`on`** \*            | The name of the relationship or upload field that relates to the collection document. Use dot notation for nested paths, like 'myGroup.relationName'.                                         |
 | **`maxDepth`**         | Default is 1, Sets a maximum population depth for this field, regardless of the remaining depth when this field is reached. [Max Depth](/docs/getting-started/concepts#field-level-max-depth) |
 | **`label`**            | Text used as a field label in the Admin Panel or an object with keys for each language.                                                                                                       |
 | **`hooks`**            | Provide Field Hooks to control logic for this field. [More details](../hooks/fields).                                                                                                         |

docs/fields/upload.mdx

@@ -6,7 +6,8 @@ desc: Upload fields will allow a file to be uploaded, only from a collection sup
 keywords: upload, images media, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs
 ---
 
-The Upload Field allows for the selection of a Document from a Collection supporting [Uploads](../upload/overview), and formats the selection as a thumbnail in the Admin Panel.
+The Upload Field allows for the selection of a Document from a Collection supporting [Uploads](../upload/overview), and
+formats the selection as a thumbnail in the Admin Panel.
 
 Upload fields are useful for a variety of use cases, such as:
 
@@ -15,10 +16,10 @@ Upload fields are useful for a variety of use cases, such as:
 - To give a layout building block the ability to feature a background image
 
 <LightDarkImage
-  srcLight="https://payloadcms.com/images/docs/fields/upload.png"
-  srcDark="https://payloadcms.com/images/docs/fields/upload-dark.png"
-  alt="Shows an upload field in the Payload Admin Panel"
-  caption="Admin Panel screenshot of an Upload field"
+srcLight="https://payloadcms.com/images/docs/fields/upload.png"
+srcDark="https://payloadcms.com/images/docs/fields/upload-dark.png"
+alt="Shows an upload field in the Payload Admin Panel"
+caption="Admin Panel screenshot of an Upload field"
 />
 
 To create an Upload Field, set the `type` to `upload` in your [Field Config](./overview):
@@ -43,7 +44,7 @@ export const MyUploadField: Field = {
 ## Config Options
 
 | Option                 | Description                                                                                                                                                                 |
-| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | **`name`** \*          | To be used as the property name when stored and retrieved from the database. [More](/docs/fields/overview#field-names)                                                      |
 | **`*relationTo`** \*   | Provide a single collection `slug` to allow this field to accept a relation to. <strong>Note: the related collection must be configured to support Uploads.</strong>        |
 | **`filterOptions`**    | A query to filter which options appear in the UI and validate against. [More](#filtering-upload-options).                                                                   |
@@ -97,7 +98,7 @@ prevent all, or a `Where` query. When using a function, it will be
 called with an argument object with the following properties:
 
 | Property      | Description                                                                                           |
-| ------------- | ----------------------------------------------------------------------------------------------------- |
+|---------------|-------------------------------------------------------------------------------------------------------|
 | `relationTo`  | The collection `slug` to filter against, limited to this field's `relationTo` property                |
 | `data`        | An object containing the full collection or global document currently being edited                    |
 | `siblingData` | An object containing document data that is scoped to only fields within the same parent of this field |
@@ -127,3 +128,10 @@ You can learn more about writing queries [here](/docs/queries/overview).
   unless you call the default upload field validation function imported from{' '}
   <strong>payload/shared</strong> in your validate function.
 </Banner>
+
+## Bi-directional relationships
+
+The `upload` field on its own is used to reference documents in an upload collection. This can be considered a "one-way"
+relationship. If you wish to allow an editor to visit the upload document and see where it is being used, you may use
+the `join` field in the upload enabled collection. Read more about bi-directional relationships using
+the [Join field](./join)

packages/payload/src/fields/config/sanitizeJoinField.ts

@@ -1,6 +1,6 @@
 import type { SanitizedJoins } from '../../collections/config/types.js'
 import type { Config } from '../../config/types.js'
-import type { JoinField, RelationshipField } from './types.js'
+import type { JoinField, RelationshipField, UploadField } from './types.js'
 
 import { APIError } from '../../errors/index.js'
 import { InvalidFieldJoin } from '../../errors/InvalidFieldJoin.js'
@@ -33,7 +33,7 @@ export const sanitizeJoinField = ({
   if (!joinCollection) {
     throw new InvalidFieldJoin(field)
   }
-  let joinRelationship: RelationshipField | undefined
+  let joinRelationship: RelationshipField | UploadField
 
   const pathSegments = field.on.split('.') // Split the schema path into segments
   let currentSegmentIndex = 0
@@ -49,9 +49,10 @@ export const sanitizeJoinField = ({
       if ('name' in field && field.name === currentSegment) {
         // Check if this is the last segment in the path
         if (
-          currentSegmentIndex === pathSegments.length - 1 &&
-          'type' in field &&
-          field.type === 'relationship'
+          (currentSegmentIndex === pathSegments.length - 1 &&
+            'type' in field &&
+            field.type === 'relationship') ||
+          field.type === 'upload'
         ) {
           joinRelationship = field // Return the matched field
           next()

packages/ui/src/elements/Table/TableCellProvider/index.tsx

@@ -28,12 +28,12 @@ export const TableCellProvider: React.FC<{
   return (
     <TableCellContext.Provider
       value={{
+        ...contextToInherit,
         cellData,
         cellProps,
         columnIndex,
         customCellContext,
         rowData,
-        ...contextToInherit,
       }}
     >
       {children}

packages/ui/src/fields/Upload/Input.tsx

@@ -153,6 +153,9 @@ export function UploadInput(props: UploadInputProps) {
     collectionSlug: activeRelationTo,
   })
 
+  /**
+   * Prevent initial retrieval of documents from running more than once
+   */
   const loadedValueDocsRef = React.useRef<boolean>(false)
 
   const canCreate = useMemo(() => {
@@ -388,6 +391,7 @@ export function UploadInput(props: UploadInputProps) {
   useEffect(() => {
     async function loadInitialDocs() {
       if (value) {
+        loadedValueDocsRef.current = true
         const loadedDocs = await populateDocs(
           Array.isArray(value) ? value : [value],
           activeRelationTo,
@@ -398,8 +402,6 @@ export function UploadInput(props: UploadInputProps) {
           )
         }
       }
-
-      loadedValueDocsRef.current = true
     }
 
     if (!loadedValueDocsRef.current) {

test/joins/.gitignore

@@ -0,0 +1 @@
+/uploads/

test/joins/collections/Posts.ts

@@ -1,6 +1,6 @@
 import type { CollectionConfig } from 'payload'
 
-import { categoriesSlug, postsSlug } from '../shared.js'
+import { categoriesSlug, postsSlug, uploadsSlug } from '../shared.js'
 
 export const Posts: CollectionConfig = {
   slug: postsSlug,
@@ -13,6 +13,11 @@ export const Posts: CollectionConfig = {
       name: 'title',
       type: 'text',
     },
+    {
+      name: 'upload',
+      type: 'upload',
+      relationTo: uploadsSlug,
+    },
     {
       name: 'category',
       type: 'relationship',

test/joins/collections/Uploads.ts

@@ -0,0 +1,23 @@
+import type { CollectionConfig } from 'payload'
+
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+import { uploadsSlug } from '../shared.js'
+const filename = fileURLToPath(import.meta.url)
+const dirname = path.dirname(filename)
+
+export const Uploads: CollectionConfig = {
+  slug: uploadsSlug,
+  fields: [
+    {
+      name: 'relatedPosts',
+      type: 'join',
+      collection: 'posts',
+      on: 'upload',
+    },
+  ],
+  upload: {
+    staticDir: path.resolve(dirname, '../uploads'),
+  },
+}

test/joins/config.ts

@@ -4,6 +4,7 @@ import path from 'path'
 import { buildConfigWithDefaults } from '../buildConfigWithDefaults.js'
 import { Categories } from './collections/Categories.js'
 import { Posts } from './collections/Posts.js'
+import { Uploads } from './collections/Uploads.js'
 import { seed } from './seed.js'
 import { localizedCategoriesSlug, localizedPostsSlug } from './shared.js'
 
@@ -14,6 +15,7 @@ export default buildConfigWithDefaults({
   collections: [
     Posts,
     Categories,
+    Uploads,
     {
       slug: localizedPostsSlug,
       admin: {

test/joins/e2e.spec.ts

@@ -10,14 +10,15 @@ import { AdminUrlUtil } from '../helpers/adminUrlUtil.js'
 import { navigateToDoc } from '../helpers/e2e/navigateToDoc.js'
 import { initPayloadE2ENoConfig } from '../helpers/initPayloadE2ENoConfig.js'
 import { TEST_TIMEOUT_LONG } from '../playwright.config.js'
-import { categoriesSlug, postsSlug } from './shared.js'
+import { categoriesSlug, postsSlug, uploadsSlug } from './shared.js'
 
 const filename = fileURLToPath(import.meta.url)
 const dirname = path.dirname(filename)
 
 test.describe('Admin Panel', () => {
   let page: Page
   let categoriesURL: AdminUrlUtil
+  let uploadsURL: AdminUrlUtil
   let postsURL: AdminUrlUtil
 
   test.beforeAll(async ({ browser }, testInfo) => {
@@ -26,6 +27,7 @@ test.describe('Admin Panel', () => {
     const { payload, serverURL } = await initPayloadE2ENoConfig({ dirname })
     postsURL = new AdminUrlUtil(serverURL, postsSlug)
     categoriesURL = new AdminUrlUtil(serverURL, categoriesSlug)
+    uploadsURL = new AdminUrlUtil(serverURL, uploadsSlug)
 
     const context = await browser.newContext()
     page = await context.newPage()
@@ -183,4 +185,65 @@ test.describe('Admin Panel', () => {
     await expect(joinField).toBeVisible()
     await expect(joinField.locator('.relationship-table tbody tr')).toBeHidden()
   })
+
+  test('should update relationship table when new upload is created', async () => {
+    await navigateToDoc(page, uploadsURL)
+    const joinField = page.locator('.field-type.join').first()
+    await expect(joinField).toBeVisible()
+
+    const addButton = joinField.locator('.relationship-table__actions button.doc-drawer__toggler', {
+      hasText: exactText('Add new'),
+    })
+
+    await expect(addButton).toBeVisible()
+
+    await addButton.click()
+    const drawer = page.locator('[id^=doc-drawer_posts_1_]')
+    await expect(drawer).toBeVisible()
+    const uploadField = drawer.locator('#field-upload')
+    await expect(uploadField).toBeVisible()
+    const uploadValue = uploadField.locator('.upload-relationship-details img')
+    await expect(uploadValue).toBeVisible()
+    const titleField = drawer.locator('#field-title')
+    await expect(titleField).toBeVisible()
+    await titleField.fill('Test post with upload')
+    await drawer.locator('button[id="action-save"]').click()
+    await expect(drawer).toBeHidden()
+    await expect(
+      joinField.locator('tbody tr td:nth-child(2)', {
+        hasText: exactText('Test post with upload'),
+      }),
+    ).toBeVisible()
+  })
+
+  test('should update relationship table when new upload is created', async () => {
+    await navigateToDoc(page, uploadsURL)
+    const joinField = page.locator('.field-type.join').first()
+    await expect(joinField).toBeVisible()
+
+    // TODO: change this to edit the first row in the join table
+    const addButton = joinField.locator('.relationship-table__actions button.doc-drawer__toggler', {
+      hasText: exactText('Add new'),
+    })
+
+    await expect(addButton).toBeVisible()
+
+    await addButton.click()
+    const drawer = page.locator('[id^=doc-drawer_posts_1_]')
+    await expect(drawer).toBeVisible()
+    const uploadField = drawer.locator('#field-upload')
+    await expect(uploadField).toBeVisible()
+    const uploadValue = uploadField.locator('.upload-relationship-details img')
+    await expect(uploadValue).toBeVisible()
+    const titleField = drawer.locator('#field-title')
+    await expect(titleField).toBeVisible()
+    await titleField.fill('Edited title for upload')
+    await drawer.locator('button[id="action-save"]').click()
+    await expect(drawer).toBeHidden()
+    await expect(
+      joinField.locator('tbody tr td:nth-child(2)', {
+        hasText: exactText('Edited title for upload'),
+      }),
+    ).toBeVisible()
+  })
 })