fix(ui): nested fields disappear when manipulating rows in form state (#11906)

Continuation of #11867. When rendering custom fields nested within
arrays or blocks, such as the Lexical rich text editor which is treated
as a custom field, these fields will sometimes disappear when form state
requests are invoked sequentially. This is especially reproducible on
slow networks.

This is different from the previous PR in that this issue is caused by
adding _rows_ back-to-back, whereas the previous issue was caused when
adding a single row followed by a change to another field.

Here's a screen recording demonstrating the issue:


https://github.com/user-attachments/assets/5ecfa9ec-b747-49ed-8618-df282e64519d

The problem is that `requiresRender` is never sent in the form state
request for row 2. This is because the [task
queue](#11579) processes tasks
within a single `useEffect`. This forces React to batch the results of
these tasks into a single rendering cycle. So if request 1 sets state
that request 2 relies on, request 2 will never use that state since
they'll execute within the same lifecycle.

Here's a play-by-play of the current behavior:

1. The "add row" event is dispatched
    a. This sets `requiresRender: true` in form state
1. A form state request is sent with `requiresRender: true`
1. While that request is processing, another "add row" event is
dispatched
    a. This sets `requiresRender: true` in form state
    b. This adds a form state request into the queue
1. The initial form state request finishes
    a. This sets `requiresRender: false` in form state
1. The next form state request that was queued up in 3b is sent with
`requiresRender: false`
    a. THIS IS EXPECTED, BUT SHOULD ACTUALLY BE `true`!!

To fix this this, we need to ensure that the `requiresRender` property
is persisted into the second request instead of overridden. To do this,
we can add a new `serverPropsToIgnore` to form state which is read when
the processing results from the server. So if `requiresRender` exists in
`serverPropsToIgnore`, we do not merge it. This works because we
actually mutate form state in between requests. So request 2 can read
the results from request 1 without going through an additional rendering
cycle.

Here's a play-by-play of the fix:

1. The "add row" event is dispatched
    a. This sets `requiresRender: true` in form state
b. This adds a task in the queue to mutate form state with
`requiresRender: true`
1. A form state request is sent with `requiresRender: true`
1. While that request is processing, another "add row" event is
dispatched
a. This sets `requiresRender: true` in form state AND
`serverPropsToIgnore: [ "requiresRender" ]`
    c. This adds a form state request into the queue
1. The initial form state request finishes
a. This returns `requiresRender: false` from the form state endpoint BUT
IS IGNORED
1. The next form state request that was queued up in 3c is sent with
`requiresRender: true`

Author: jacobsfletch

packages/payload/src/admin/forms/Form.ts

@@ -49,6 +49,18 @@ export type FieldState = {
   passesCondition?: boolean
   requiresRender?: boolean
   rows?: Row[]
+  /**
+   * The `serverPropsToIgnore` obj is used to prevent the various properties from being overridden across form state requests.
+   * This can happen when queueing a form state request with `requiresRender: true` while the another is already processing.
+   * For example:
+   *   1. One "add row" action will set `requiresRender: true` and dispatch a form state request
+   *   2. Another "add row" action will set `requiresRender: true` and queue a form state request
+   *   3. The first request will return with `requiresRender: false`
+   *   4. The second request will be dispatched with `requiresRender: false` but should be `true`
+   * To fix this, only merge the `requiresRender` property if the previous state has not set it to `true`.
+   * See the `mergeServerFormState` function for implementation details.
+   */
+  serverPropsToIgnore?: Array<keyof FieldState>
   valid?: boolean
   validate?: Validate
   value?: unknown

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

@@ -58,7 +58,7 @@ export const ArrayFieldComponent: ArrayFieldClientComponent = (props) => {
   const minRows = (minRowsProp ?? required) ? 1 : 0
 
   const { setDocFieldPreferences } = useDocumentInfo()
-  const { addFieldRow, dispatchFields, setModified } = useForm()
+  const { addFieldRow, dispatchFields, moveFieldRow, removeFieldRow, setModified } = useForm()
   const submitted = useFormSubmitted()
   const { code: locale } = useLocale()
   const { i18n, t } = useTranslation()
@@ -153,18 +153,20 @@ export const ArrayFieldComponent: ArrayFieldClientComponent = (props) => {
 
   const removeRow = useCallback(
     (rowIndex: number) => {
-      dispatchFields({ type: 'REMOVE_ROW', path, rowIndex })
-      setModified(true)
+      removeFieldRow({ path, rowIndex })
     },
-    [dispatchFields, path, setModified],
+    [removeFieldRow, path],
   )
 
   const moveRow = useCallback(
     (moveFromIndex: number, moveToIndex: number) => {
-      dispatchFields({ type: 'MOVE_ROW', moveFromIndex, moveToIndex, path })
-      setModified(true)
+      moveFieldRow({
+        moveFromIndex,
+        moveToIndex,
+        path,
+      })
     },
-    [dispatchFields, path, setModified],
+    [path, moveFieldRow],
   )
 
   const toggleCollapseAll = useCallback(

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

@@ -60,7 +60,7 @@ const BlocksFieldComponent: BlocksFieldClientComponent = (props) => {
   const minRows = (minRowsProp ?? required) ? 1 : 0
 
   const { setDocFieldPreferences } = useDocumentInfo()
-  const { addFieldRow, dispatchFields, setModified } = useForm()
+  const { addFieldRow, dispatchFields, moveFieldRow, removeFieldRow, setModified } = useForm()
   const { code: locale } = useLocale()
   const {
     config: { localization },
@@ -141,23 +141,19 @@ const BlocksFieldComponent: BlocksFieldClientComponent = (props) => {
 
   const removeRow = useCallback(
     (rowIndex: number) => {
-      dispatchFields({
-        type: 'REMOVE_ROW',
+      removeFieldRow({
         path,
         rowIndex,
       })
-
-      setModified(true)
     },
-    [path, dispatchFields, setModified],
+    [path, removeFieldRow],
   )
 
   const moveRow = useCallback(
     (moveFromIndex: number, moveToIndex: number) => {
-      dispatchFields({ type: 'MOVE_ROW', moveFromIndex, moveToIndex, path })
-      setModified(true)
+      moveFieldRow({ moveFromIndex, moveToIndex, path })
     },
-    [dispatchFields, path, setModified],
+    [moveFieldRow, path],
   )
 
   const toggleCollapseAll = useCallback(
@@ -166,6 +162,7 @@ const BlocksFieldComponent: BlocksFieldClientComponent = (props) => {
         collapsed,
         rows,
       })
+
       dispatchFields({ type: 'SET_ALL_ROWS_COLLAPSED', path, updatedRows })
       setDocFieldPreferences(path, { collapsed: collapsedIDs })
     },
@@ -179,6 +176,7 @@ const BlocksFieldComponent: BlocksFieldClientComponent = (props) => {
         rowID,
         rows,
       })
+
       dispatchFields({ type: 'SET_ROW_COLLAPSED', path, updatedRows })
       setDocFieldPreferences(path, { collapsed: collapsedIDs })
     },

packages/ui/src/forms/Form/fieldReducer.ts

@@ -63,6 +63,14 @@ export function fieldReducer(state: FormState, action: FieldAction): FormState {
           requiresRender: true,
           rows: withNewRow,
           value: siblingRows.length,
+          ...(state[path]?.requiresRender === true
+            ? {
+                serverPropsToIgnore: [
+                  ...(state[path]?.serverPropsToIgnore || []),
+                  'requiresRender',
+                ],
+              }
+            : state[path]?.serverPropsToIgnore || []),
         },
       }
 
@@ -172,6 +180,14 @@ export function fieldReducer(state: FormState, action: FieldAction): FormState {
           requiresRender: true,
           rows: rowsMetadata,
           value: rows.length,
+          ...(state[path]?.requiresRender === true
+            ? {
+                serverPropsToIgnore: [
+                  ...(state[path]?.serverPropsToIgnore || []),
+                  'requiresRender',
+                ],
+              }
+            : state[path]?.serverPropsToIgnore || ([] as any)),
         },
       }
 
@@ -200,6 +216,14 @@ export function fieldReducer(state: FormState, action: FieldAction): FormState {
           ...state[path],
           requiresRender: true,
           rows: rowsWithinField,
+          ...(state[path]?.requiresRender === true
+            ? {
+                serverPropsToIgnore: [
+                  ...(state[path]?.serverPropsToIgnore || []),
+                  'requiresRender',
+                ],
+              }
+            : state[path]?.serverPropsToIgnore || ([] as any)),
         },
       }
 
@@ -218,9 +242,8 @@ export function fieldReducer(state: FormState, action: FieldAction): FormState {
 
         const copyOfMovingLabel = customComponents.RowLabels[moveFromIndex]
 
-        // eslint-disable-next-line @typescript-eslint/no-floating-promises
         customComponents.RowLabels.splice(moveFromIndex, 1)
-        // eslint-disable-next-line @typescript-eslint/no-floating-promises
+
         customComponents.RowLabels.splice(moveToIndex, 0, copyOfMovingLabel)
 
         newState[path].customComponents = customComponents
@@ -253,6 +276,14 @@ export function fieldReducer(state: FormState, action: FieldAction): FormState {
           requiresRender: true,
           rows: rowsMetadata,
           value: rows.length,
+          ...(state[path]?.requiresRender === true
+            ? {
+                serverPropsToIgnore: [
+                  ...(state[path]?.serverPropsToIgnore || []),
+                  'requiresRender',
+                ],
+              }
+            : state[path]?.serverPropsToIgnore || []),
         },
         ...flattenRows(path, rows),
       }
@@ -292,6 +323,14 @@ export function fieldReducer(state: FormState, action: FieldAction): FormState {
           disableFormData: true,
           rows: rowsMetadata,
           value: siblingRows.length,
+          ...(state[path]?.requiresRender === true
+            ? {
+                serverPropsToIgnore: [
+                  ...(state[path]?.serverPropsToIgnore || []),
+                  'requiresRender',
+                ],
+              }
+            : state[path]?.serverPropsToIgnore || []),
         },
       }
 
@@ -327,7 +366,7 @@ export function fieldReducer(state: FormState, action: FieldAction): FormState {
         return newState
       }
 
-      //TODO: Remove this in 4.0 - this is a temporary fix to prevent a breaking change
+      // TODO: Remove this in 4.0 - this is a temporary fix to prevent a breaking change
       if (action.sanitize) {
         for (const field of Object.values(action.state)) {
           if (field.valid !== false) {

packages/ui/src/forms/Form/index.tsx

@@ -121,11 +121,11 @@ export const Form: React.FC<FormProps> = (props) => {
 
   const fieldsReducer = useReducer(fieldReducer, {}, () => initialState)
 
-  const [fields, dispatchFields] = fieldsReducer
+  const [formState, dispatchFields] = fieldsReducer
 
-  contextRef.current.fields = fields
+  contextRef.current.fields = formState
 
-  const prevFields = useRef(fields)
+  const prevFormState = useRef(formState)
 
   const validateForm = useCallback(async () => {
     const validatedFieldState = {}
@@ -611,9 +611,25 @@ export const Form: React.FC<FormProps> = (props) => {
     [dispatchFields, getDataByPath],
   )
 
+  const moveFieldRow: FormContextType['moveFieldRow'] = useCallback(
+    ({ moveFromIndex, moveToIndex, path }) => {
+      dispatchFields({
+        type: 'MOVE_ROW',
+        moveFromIndex,
+        moveToIndex,
+        path,
+      })
+
+      setModified(true)
+    },
+    [dispatchFields],
+  )
+
   const removeFieldRow: FormContextType['removeFieldRow'] = useCallback(
     ({ path, rowIndex }) => {
       dispatchFields({ type: 'REMOVE_ROW', path, rowIndex })
+
+      setModified(true)
     },
     [dispatchFields],
   )
@@ -672,6 +688,7 @@ export const Form: React.FC<FormProps> = (props) => {
   contextRef.current.dispatchFields = dispatchFields
   contextRef.current.addFieldRow = addFieldRow
   contextRef.current.removeFieldRow = removeFieldRow
+  contextRef.current.moveFieldRow = moveFieldRow
   contextRef.current.replaceFieldRow = replaceFieldRow
   contextRef.current.uuid = uuid
   contextRef.current.initializing = initializing
@@ -710,7 +727,7 @@ export const Form: React.FC<FormProps> = (props) => {
       refreshCookie()
     },
     15000,
-    [fields],
+    [formState],
   )
 
   useEffect(() => {
@@ -743,7 +760,7 @@ export const Form: React.FC<FormProps> = (props) => {
         })
 
         if (changed) {
-          prevFields.current = newState
+          prevFormState.current = newState
 
           dispatchFields({
             type: 'REPLACE_STATE',
@@ -757,14 +774,14 @@ export const Form: React.FC<FormProps> = (props) => {
 
   useDebouncedEffect(
     () => {
-      if ((isFirstRenderRef.current || !dequal(fields, prevFields.current)) && modified) {
+      if ((isFirstRenderRef.current || !dequal(formState, prevFormState.current)) && modified) {
         executeOnChange(submitted)
       }
 
-      prevFields.current = fields
+      prevFormState.current = formState
       isFirstRenderRef.current = false
     },
-    [modified, submitted, fields],
+    [modified, submitted, formState],
     250,
   )
 
@@ -793,7 +810,7 @@ export const Form: React.FC<FormProps> = (props) => {
         <FormContext value={contextRef.current}>
           <FormWatchContext
             value={{
-              fields,
+              fields: formState,
               ...contextRef.current,
             }}
           >

packages/ui/src/forms/Form/initContextState.ts

@@ -41,6 +41,7 @@ export const initContextState: Context = {
   getSiblingData,
   initializing: undefined,
   isValid: true,
+  moveFieldRow: () => undefined,
   removeFieldRow: () => undefined,
   replaceFieldRow: () => undefined,
   replaceState: () => undefined,

packages/ui/src/forms/Form/mergeServerFormState.ts

@@ -1,4 +1,6 @@
 'use client'
+import type { FieldState } from 'payload'
+
 import { dequal } from 'dequal/lite' // lite: no need for Map and Set support
 import { type FormState } from 'payload'
 
@@ -27,7 +29,7 @@ export const mergeServerFormState = ({
   const newState = {}
 
   if (existingState) {
-    const serverPropsToAccept = [
+    const serverPropsToAccept: Array<keyof FieldState> = [
       'passesCondition',
       'valid',
       'errorMessage',
@@ -46,6 +48,7 @@ export const mergeServerFormState = ({
       if (!incomingState[path]) {
         continue
       }
+
       let fieldChanged = false
 
       /**
@@ -55,6 +58,7 @@ export const mergeServerFormState = ({
         newFieldState.errorPaths,
         incomingState[path].errorPaths as unknown as string[],
       )
+
       if (errorPathsResult.result) {
         if (errorPathsResult.changed) {
           changed = errorPathsResult.changed
@@ -76,25 +80,41 @@ export const mergeServerFormState = ({
       /**
        * Handle adding all the remaining props that should be updated in the local form state from the server form state
        */
-      serverPropsToAccept.forEach((prop) => {
-        if (!dequal(incomingState[path]?.[prop], newFieldState[prop])) {
+      serverPropsToAccept.forEach((propFromServer) => {
+        if (!dequal(incomingState[path]?.[propFromServer], newFieldState[propFromServer])) {
           changed = true
           fieldChanged = true
-          if (!(prop in incomingState[path])) {
+
+          if (newFieldState?.serverPropsToIgnore?.includes(propFromServer)) {
+            // Remove the ignored prop for the next request
+            newFieldState.serverPropsToIgnore = newFieldState.serverPropsToIgnore.filter(
+              (prop) => prop !== propFromServer,
+            )
+
+            // if no keys left, remove the entire object
+            if (!newFieldState.serverPropsToIgnore.length) {
+              delete newFieldState.serverPropsToIgnore
+            }
+
+            return
+          }
+
+          if (!(propFromServer in incomingState[path])) {
             // Regarding excluding the customComponents prop from being deleted: the incoming state might not have been rendered, as rendering components for every form onchange is expensive.
             // Thus, we simply re-use the initial render state
-            if (prop !== 'customComponents') {
-              delete newFieldState[prop]
+            if (propFromServer !== 'customComponents') {
+              delete newFieldState[propFromServer]
             }
           } else {
-            newFieldState[prop] = incomingState[path][prop]
+            newFieldState[propFromServer as any] = incomingState[path][propFromServer]
           }
         }
       })
 
       if (newFieldState.valid !== false) {
         newFieldState.valid = true
       }
+
       if (newFieldState.passesCondition !== false) {
         newFieldState.passesCondition = true
       }
@@ -106,7 +126,6 @@ export const mergeServerFormState = ({
     // Now loop over values that are part of incoming state but not part of existing state, and add them to the new state.
     // This can happen if a new array row was added. In our local state, we simply add out stubbed `array` and `array.[index].id` entries to the local form state.
     // However, all other array sub-fields are not added to the local state - those will be added by the server and may be incoming here.
-
     for (const [path, field] of Object.entries(incomingState)) {
       if (!existingState[path]) {
         changed = true