fix(ui): relationship field label not updated when document is updated from other drawer (#14609)

When updating a document from a document drawer that isn’t the one
associated with a relationship field, the relationship’s label doesn’t
update correctly.

## Reproduction

This issue is easily reproducible when two relationship fields link to
the same document. If you update the document from the drawer of one
field, the other field will not reflect the update. This happens because
each field only listens to the `onSave` event of its own document
drawer.

## Fix

Use the `useDocumentEvents` hook instead of the `onSave` hook.
`useDocumentEvents` listens for updates to all saved documents, ensuring
that all relationship fields stay in sync regardless of which drawer the
update originated from.

**Before:**


https://github.com/user-attachments/assets/eda152fe-3cda-4111-b0f3-9f0d5a48f37b


**After:**


https://github.com/user-attachments/assets/da252d3d-c0a9-43ee-91d8-508e302d323e

Author: AlessioGr

packages/payload/src/admin/types.ts

@@ -2,6 +2,7 @@ import type { AcceptedLanguages, I18nClient } from '@payloadcms/translations'
 import type React from 'react'
 
 import type { ImportMap } from '../bin/generateImportMap/index.js'
+import type { TypeWithID } from '../collections/config/types.js'
 import type { SanitizedConfig } from '../config/types.js'
 import type {
   Block,
@@ -717,7 +718,10 @@ export type ClientFieldSchemaMap = Map<
 >
 
 export type DocumentEvent = {
+  doc?: TypeWithID
+  drawerSlug?: string
   entitySlug: string
   id?: number | string
+  operation: 'create' | 'update'
   updatedAt: string
 }

packages/ui/src/elements/BulkUpload/EditForm/index.tsx

@@ -43,7 +43,7 @@ export function EditForm({
     Upload: CustomUpload,
   } = useDocumentInfo()
 
-  const { onSave: onSaveFromContext } = useDocumentDrawerContext()
+  const { drawerSlug, onSave: onSaveFromContext } = useDocumentDrawerContext()
 
   const { getFormState } = useServerFunctions()
 
@@ -64,7 +64,10 @@ export function EditForm({
   const onSave = useCallback(
     (json) => {
       reportUpdate({
+        doc: json?.doc || json?.result,
+        drawerSlug,
         entitySlug: collectionSlug,
+        operation: 'create',
         updatedAt: json?.result?.updatedAt || new Date().toISOString(),
       })
 
@@ -76,7 +79,7 @@ export function EditForm({
       }
       resetUploadEdits()
     },
-    [collectionSlug, onSaveFromContext, reportUpdate, resetUploadEdits],
+    [collectionSlug, onSaveFromContext, reportUpdate, resetUploadEdits, drawerSlug],
   )
 
   const onChange: NonNullable<FormProps['onChange']>[0] = useCallback(

packages/ui/src/elements/DocumentDrawer/Provider.tsx

@@ -41,7 +41,9 @@ export const DocumentDrawerContextProvider: React.FC<
     children: React.ReactNode
   } & DocumentDrawerContextProps
 > = ({ children, ...rest }) => {
-  return <DocumentDrawerCallbacksContext value={rest}>{children}</DocumentDrawerCallbacksContext>
+  return (
+    <DocumentDrawerCallbacksContext value={{ ...rest }}>{children}</DocumentDrawerCallbacksContext>
+  )
 }
 
 export const useDocumentDrawerContext = (): DocumentDrawerContextType => {

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

@@ -1,5 +1,11 @@
 'use client'
-import type { FilterOptionsResult, PaginatedDocs, ValueWithRelation, Where } from 'payload'
+import type {
+  DocumentEvent,
+  FilterOptionsResult,
+  PaginatedDocs,
+  ValueWithRelation,
+  Where,
+} from 'payload'
 
 import { dequal } from 'dequal/lite'
 import { formatAdminURL, wordBoundariesRegex } from 'payload/shared'
@@ -24,15 +30,16 @@ import { useEffectEvent } from '../../hooks/useEffectEvent.js'
 import { useQueue } from '../../hooks/useQueue.js'
 import { useAuth } from '../../providers/Auth/index.js'
 import { useConfig } from '../../providers/Config/index.js'
+import { useDocumentEvents } from '../../providers/DocumentEvents/index.js'
 import { useLocale } from '../../providers/Locale/index.js'
 import { useTranslation } from '../../providers/Translation/index.js'
 import { sanitizeFilterOptionsQuery } from '../../utilities/sanitizeFilterOptionsQuery.js'
 import { fieldBaseClass } from '../shared/index.js'
 import { createRelationMap } from './createRelationMap.js'
 import { findOptionsByValue } from './findOptionsByValue.js'
 import { optionsReducer } from './optionsReducer.js'
-import { MultiValueLabel } from './select-components/MultiValueLabel/index.js'
 import './index.scss'
+import { MultiValueLabel } from './select-components/MultiValueLabel/index.js'
 import { SingleValue } from './select-components/SingleValue/index.js'
 
 const baseClass = 'relationship'
@@ -102,7 +109,7 @@ export const RelationshipInput: React.FC<RelationshipInputProps> = (props) => {
 
   const valueRef = useRef(value)
 
-  const [DocumentDrawer, , { isDrawerOpen, openDrawer }] = useDocumentDrawer({
+  const [DocumentDrawer, , { drawerSlug, isDrawerOpen, openDrawer }] = useDocumentDrawer({
     id: currentlyOpenRelationship.id,
     collectionSlug: currentlyOpenRelationship.collectionSlug,
   })
@@ -467,35 +474,75 @@ export const RelationshipInput: React.FC<RelationshipInputProps> = (props) => {
     }, Promise.resolve())
   })
 
-  const onSave = useCallback<DocumentDrawerProps['onSave']>(
-    (args) => {
-      dispatchOptions({
-        type: 'UPDATE',
-        collection: args.collectionConfig,
-        config,
-        doc: args.doc,
-        i18n,
-      })
+  const { mostRecentUpdate } = useDocumentEvents()
 
-      const docID = args.doc.id
+  const handleDocumentUpdateEvent = useEffectEvent((mostRecentUpdate: DocumentEvent) => {
+    if (!value) {
+      return false
+    }
 
-      if (hasMany) {
-        const currentValue = value ? (Array.isArray(value) ? value : [value]) : []
+    const docID = mostRecentUpdate.doc.id
 
-        const valuesToSet = currentValue.map((option: ValueWithRelation) => {
-          return {
-            relationTo: option.value === docID ? args.collectionConfig.slug : option.relationTo,
-            value: option.value,
-          }
+    let isMatchingUpdate = false
+    if (mostRecentUpdate.operation === 'update') {
+      if (hasMany === true) {
+        const currentValue = Array.isArray(value) ? value : [value]
+        isMatchingUpdate = currentValue.some((option) => {
+          return option.value === docID && option.relationTo === mostRecentUpdate.entitySlug
         })
-
-        onChange(valuesToSet)
       } else if (hasMany === false) {
-        onChange({ relationTo: args.collectionConfig.slug, value: docID })
+        isMatchingUpdate =
+          value?.value === docID && value?.relationTo === mostRecentUpdate.entitySlug
       }
-    },
-    [i18n, config, hasMany, onChange, value],
-  )
+    } else if (mostRecentUpdate.operation === 'create') {
+      // "Create New" drawer operations on the same level as this drawer should
+      // set the value to the newly created document.
+      // See test "should create document within document drawer > has one"
+      isMatchingUpdate = mostRecentUpdate.drawerSlug === drawerSlug
+    }
+
+    if (!isMatchingUpdate) {
+      return
+    }
+
+    const collectionConfig = getEntityConfig({ collectionSlug: mostRecentUpdate.entitySlug })
+
+    dispatchOptions({
+      type: 'UPDATE',
+      collection: collectionConfig,
+      config,
+      doc: mostRecentUpdate.doc,
+      i18n,
+    })
+
+    if (hasMany) {
+      const currentValue = value ? (Array.isArray(value) ? value : [value]) : []
+
+      const valuesToSet = currentValue.map((option: ValueWithRelation) => {
+        return {
+          relationTo: option.value === docID ? mostRecentUpdate.entitySlug : option.relationTo,
+          value: option.value,
+        }
+      })
+
+      onChange(valuesToSet)
+    } else if (hasMany === false) {
+      onChange({ relationTo: mostRecentUpdate.entitySlug, value: docID })
+    }
+  })
+
+  /**
+   * Listen to document update events. If you edit a related document from a drawer and save it, this event
+   * will be triggered. We then need up update the label of this relationship input, as the useAsLabel field could have changed.
+   *
+   * We listen to this event instead of using the onSave callback on the document drawer, as the onSave callback is not triggered
+   * when you save a document from a drawer opened by a *different* relationship (or any other) field.
+   */
+  useEffect(() => {
+    if (mostRecentUpdate) {
+      handleDocumentUpdateEvent(mostRecentUpdate)
+    }
+  }, [mostRecentUpdate])
 
   const onDuplicate = useCallback<DocumentDrawerProps['onDuplicate']>(
     (args) => {
@@ -729,7 +776,6 @@ export const RelationshipInput: React.FC<RelationshipInputProps> = (props) => {
                 disableKeyDown: isDrawerOpen || isListDrawerOpen,
                 disableMouseDown: isDrawerOpen || isListDrawerOpen,
                 onDocumentOpen,
-                onSave,
               }}
               disabled={readOnly || isDrawerOpen || isListDrawerOpen}
               filterOption={enableWordBoundarySearch ? filterOption : undefined}
@@ -870,7 +916,7 @@ export const RelationshipInput: React.FC<RelationshipInputProps> = (props) => {
         />
       </div>
       {currentlyOpenRelationship.collectionSlug && currentlyOpenRelationship.hasReadPermission && (
-        <DocumentDrawer onDelete={onDelete} onDuplicate={onDuplicate} onSave={onSave} />
+        <DocumentDrawer onDelete={onDelete} onDuplicate={onDuplicate} />
       )}
       {appearance === 'drawer' && !readOnly && (
         <ListDrawer allowCreate={allowCreate} enableRowSelections={false} onSelect={onListSelect} />

packages/ui/src/fields/Relationship/index.tsx

@@ -3,7 +3,7 @@ import type { RelationshipFieldClientComponent, ValueWithRelation } from 'payloa
 
 import React, { useCallback, useMemo } from 'react'
 
-import type { PolymorphicRelationValue, Value } from './types.js'
+import type { Value } from './types.js'
 
 import { useField } from '../../forms/useField/index.js'
 import { withCondition } from '../../forms/withCondition/index.js'
@@ -80,7 +80,7 @@ const RelationshipFieldComponent: RelationshipFieldClientComponent = (props) =>
           Array.isArray(value) &&
           Array.isArray(newValue) &&
           value.length === newValue.length &&
-          (value as PolymorphicRelationValue[]).every((val, idx) => {
+          (value as ValueWithRelation[]).every((val, idx) => {
             const newVal = newValue[idx]
             return val.value === newVal.value && val.relationTo === newVal.relationTo
           })
@@ -117,8 +117,8 @@ const RelationshipFieldComponent: RelationshipFieldClientComponent = (props) =>
         disableFormModification =
           value &&
           newValue &&
-          (value as PolymorphicRelationValue).value === newValue.value &&
-          (value as PolymorphicRelationValue).relationTo === newValue.relationTo
+          (value as ValueWithRelation).value === newValue.value &&
+          (value as ValueWithRelation).relationTo === newValue.relationTo
       } else {
         disableFormModification = value && newValue && value === newValue.value
       }

packages/ui/src/fields/Relationship/types.ts

@@ -7,6 +7,7 @@ import type {
   LabelFunction,
   StaticDescription,
   StaticLabel,
+  ValueWithRelation,
 } from 'payload'
 
 export type Option = {
@@ -22,21 +23,16 @@ export type OptionGroup = {
   options: Option[]
 }
 
-export type PolymorphicRelationValue = {
-  relationTo: string
-  value: number | string
-}
-
 export type MonomorphicRelationValue = number | string
 
 export type Value =
   | MonomorphicRelationValue
   | MonomorphicRelationValue[]
-  | PolymorphicRelationValue
-  | PolymorphicRelationValue[]
+  | ValueWithRelation
+  | ValueWithRelation[]
 
 type CLEAR = {
-  exemptValues?: PolymorphicRelationValue | PolymorphicRelationValue[]
+  exemptValues?: ValueWithRelation | ValueWithRelation[]
   type: 'CLEAR'
 }
 
@@ -71,11 +67,11 @@ export type Action = ADD | CLEAR | REMOVE | UPDATE
 export type HasManyValueUnion =
   | {
       hasMany: false
-      value?: PolymorphicRelationValue
+      value?: ValueWithRelation
     }
   | {
       hasMany: true
-      value?: PolymorphicRelationValue[]
+      value?: ValueWithRelation[]
     }
 
 export type UpdateResults = (
@@ -121,13 +117,13 @@ export type RelationshipInputProps = {
 type SharedRelationshipInputProps =
   | {
       readonly hasMany: false
-      readonly initialValue?: null | PolymorphicRelationValue
-      readonly onChange: (value: PolymorphicRelationValue) => void
-      readonly value?: null | PolymorphicRelationValue
+      readonly initialValue?: null | ValueWithRelation
+      readonly onChange: (value: ValueWithRelation) => void
+      readonly value?: null | ValueWithRelation
     }
   | {
       readonly hasMany: true
-      readonly initialValue?: null | PolymorphicRelationValue[]
-      readonly onChange: (value: PolymorphicRelationValue[]) => void
-      readonly value?: null | PolymorphicRelationValue[]
+      readonly initialValue?: null | ValueWithRelation[]
+      readonly onChange: (value: ValueWithRelation[]) => void
+      readonly value?: null | ValueWithRelation[]
     }

packages/ui/src/providers/DocumentEvents/index.tsx

@@ -3,9 +3,12 @@ import type { DocumentEvent } from 'payload'
 
 import React, { createContext, use, useState } from 'react'
 
-const Context = createContext({
+const Context = createContext<{
+  mostRecentUpdate: DocumentEvent | null
+  reportUpdate: (event: DocumentEvent) => void
+}>({
   mostRecentUpdate: null,
-  reportUpdate: (doc: DocumentEvent) => null,
+  reportUpdate: () => null,
 })
 
 export const DocumentEventsProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
@@ -14,4 +17,11 @@ export const DocumentEventsProvider: React.FC<{ children: React.ReactNode }> = (
   return <Context value={{ mostRecentUpdate, reportUpdate }}>{children}</Context>
 }
 
+/**
+ * The useDocumentEvents hook provides a way of subscribing to cross-document events,
+ * such as updates made to nested documents within a drawer.
+ * This hook will report document events that are outside the scope of the document currently being edited.
+ *
+ * @link https://payloadcms.com/docs/admin/react-hooks#usedocumentevents
+ */
 export const useDocumentEvents = () => use(Context)

packages/ui/src/views/Edit/index.tsx

@@ -112,7 +112,6 @@ export function DefaultEditView({
     onRestore,
     onSave: onSaveFromContext,
   } = useDocumentDrawerContext()
-  const { closeModal } = useModal()
 
   const isInDrawer = Boolean(drawerSlug)
 
@@ -373,20 +372,33 @@ export function DefaultEditView({
 
         reportUpdate({
           id,
+          doc: document,
+          drawerSlug,
           entitySlug,
+          operation: 'update',
           updatedAt,
         })
 
         abortOnSaveRef.current = null
 
         return state
+      } else {
+        reportUpdate({
+          id,
+          doc: document,
+          drawerSlug,
+          entitySlug,
+          operation: 'create',
+          updatedAt,
+        })
       }
     },
     [
       reportUpdate,
       id,
       entitySlug,
       user,
+      drawerSlug,
       collectionSlug,
       userSlug,
       setLastUpdateTime,

test/fields/baseConfig.ts

@@ -41,7 +41,7 @@ import UploadRestricted from './collections/UploadRestricted/index.js'
 import Uploads3 from './collections/Uploads3/index.js'
 import { seed } from './seed.js'
 
-export const collectionSlugs: CollectionConfig[] = [
+export const collections: CollectionConfig[] = [
   {
     slug: 'users',
     admin: {
@@ -92,7 +92,7 @@ export const collectionSlugs: CollectionConfig[] = [
 ]
 
 export const baseConfig: Partial<Config> = {
-  collections: collectionSlugs,
+  collections,
   blocks: [
     {
       slug: 'ConfigBlockTest',