fix(ui): autosave not queued while background process is in flight (#14805)

When editing fields while an autosave is in flight, subsequent autosave
events are not queued as expected. This results in inconsistency between
what appears on the screen and what is persisted to the database, due to
race conditions in background processing.

For example:

https://github.com/user-attachments/assets/010f846c-ed07-4594-883e-3c60114e9f9e

This is especially noticeable in virtual fields, `useAsTitle`, and Live
Preview, where the displayed values are a direct representation of the
database, not local to form state.

The problem is related to how we manage `modified` form context. After
successful submissions, we set this flag to false. This means if the
user had made underlying changes to the form while a previous submission
was processing, e.g. an autosave, the modified state gets wrongfully
cleared and the next autosave bails out.

Potentially related: #12691

Author: jacobsfletch

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

@@ -75,24 +75,6 @@ export const Autosave: React.FC<Props> = ({ id, collection, global: globalDoc })
 
   const debouncedFormState = useDebounce(formState, interval)
 
-  const formStateRef = useRef(formState)
-  const modifiedRef = useRef(modified)
-  const localeRef = useRef(locale)
-
-  // Store fields in ref so the autosave func
-  // can always retrieve the most to date copies
-  // after the timeout has executed
-  formStateRef.current = formState
-
-  // Store modified in ref so the autosave func
-  // can bail out if modified becomes false while
-  // timing out during autosave
-  modifiedRef.current = modified
-
-  // Store locale in ref so the autosave func
-  // can always retrieve the most to date locale
-  localeRef.current = locale
-
   const { queueTask } = useQueue()
 
   const autosaveTimeoutRef = useRef<NodeJS.Timeout | null>(null)
@@ -130,21 +112,21 @@ export const Autosave: React.FC<Props> = ({ id, collection, global: globalDoc })
 
           if (collection && id) {
             entitySlug = collection.slug
-            url = `${serverURL}${api}/${entitySlug}/${id}?depth=0&draft=true&autosave=true&locale=${localeRef.current}&fallback-locale=null`
+            url = `${serverURL}${api}/${entitySlug}/${id}?depth=0&draft=true&autosave=true&locale=${locale}&fallback-locale=null`
             method = 'PATCH'
           }
 
           if (globalDoc) {
             entitySlug = globalDoc.slug
-            url = `${serverURL}${api}/globals/${entitySlug}?depth=0&draft=true&autosave=true&locale=${localeRef.current}&fallback-locale=null`
+            url = `${serverURL}${api}/globals/${entitySlug}?depth=0&draft=true&autosave=true&locale=${locale}&fallback-locale=null`
             method = 'POST'
           }
 
-          const { valid } = reduceFieldsToValuesWithValidation(formStateRef.current, true)
+          const { valid } = reduceFieldsToValuesWithValidation(formState, true)
 
           const skipSubmission = submitted && !valid && validateOnDraft
 
-          if (!skipSubmission && modifiedRef.current && url) {
+          if (!skipSubmission && modified && url) {
             const result = await submit<any, OnSaveContext>({
               acceptValues: {
                 overrideLocalChanges: false,

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

@@ -106,7 +106,8 @@ export const Form: React.FC<FormProps> = (props) => {
 
   const [disabled, setDisabled] = useState(disabledFromProps || false)
   const [isMounted, setIsMounted] = useState(false)
-  const [modified, setModified] = useState(false)
+
+  const [submitted, setSubmitted] = useState(false)
 
   /**
    * Tracks wether the form state passes validation.
@@ -116,9 +117,50 @@ export const Form: React.FC<FormProps> = (props) => {
   const [initializing, setInitializing] = useState(initializingFromProps)
 
   const [processing, setProcessing] = useState(false)
-  const [backgroundProcessing, setBackgroundProcessing] = useState(false)
 
-  const [submitted, setSubmitted] = useState(false)
+  /**
+   * Determines whether the form is processing asynchronously in the background, e.g. autosave is running.
+   * Useful to determine whether to disable the form or queue other processes while in flight, e.g. disable manual submits while an autosave is running.
+   */
+  const [backgroundProcessing, _setBackgroundProcessing] = useState(false)
+
+  /**
+   * A ref that can be read within the `setModified` interceptor.
+   * Dependents of this state can read it immediately without needing to wait for a render cycle.
+   */
+  const backgroundProcessingRef = useRef(backgroundProcessing)
+
+  /**
+   * Flag to track if the form was modified _during a submission_, e.g. while autosave is running.
+   * Useful in order to avoid resetting `modified` to false wrongfully after a submit.
+   * For example, if the user modifies a field while the a background process (autosave) is running,
+   * we need to ensure that after the submit completes, the `modified` state remains true.
+   */
+  const modifiedWhileProcessingRef = useRef(false)
+
+  /**
+   * Intercept the `setBackgroundProcessing` method to keep the ref in sync.
+   * See the `backgroundProcessingRef` for more details.
+   */
+  const setBackgroundProcessing = useCallback((backgroundProcessing: boolean) => {
+    backgroundProcessingRef.current = backgroundProcessing
+    _setBackgroundProcessing(backgroundProcessing)
+  }, [])
+
+  const [modified, _setModified] = useState(false)
+
+  /**
+   * Intercept the `setModified` method to track whether the event happened during background processing.
+   * See the `modifiedWhileProcessingRef` ref for more details.
+   */
+  const setModified = useCallback((modified: boolean) => {
+    if (backgroundProcessingRef.current) {
+      modifiedWhileProcessingRef.current = true
+    }
+
+    _setModified(modified)
+  }, [])
+
   const formRef = useRef<HTMLFormElement>(null)
   const contextRef = useRef({} as FormContextType)
   const abortResetFormRef = useRef<AbortController>(null)
@@ -360,7 +402,12 @@ export const Form: React.FC<FormProps> = (props) => {
           res = await action(formData)
         }
 
-        setModified(false)
+        if (!modifiedWhileProcessingRef.current) {
+          setModified(false)
+        } else {
+          modifiedWhileProcessingRef.current = false
+        }
+
         setDisabled(false)
 
         if (typeof handleResponse === 'function') {
@@ -412,6 +459,7 @@ export const Form: React.FC<FormProps> = (props) => {
           // Also keep the form as modified so the save button remains enabled for retry.
           if (overridesFromArgs['_status'] === 'draft') {
             setModified(true)
+
             if (!validateDrafts) {
               setSubmitted(false)
             }
@@ -498,6 +546,8 @@ export const Form: React.FC<FormProps> = (props) => {
       i18n,
       validateDrafts,
       waitForAutocomplete,
+      setModified,
+      setSubmitted,
     ],
   )
 
@@ -612,6 +662,7 @@ export const Form: React.FC<FormProps> = (props) => {
       docPermissions,
       getDocPreferences,
       locale,
+      setModified,
     ],
   )
 
@@ -621,7 +672,7 @@ export const Form: React.FC<FormProps> = (props) => {
       setModified(false)
       dispatchFields({ type: 'REPLACE_STATE', state })
     },
-    [dispatchFields],
+    [dispatchFields, setModified],
   )
 
   const addFieldRow: FormContextType['addFieldRow'] = useCallback(
@@ -641,7 +692,7 @@ export const Form: React.FC<FormProps> = (props) => {
 
       setModified(true)
     },
-    [dispatchFields, getDataByPath],
+    [dispatchFields, getDataByPath, setModified],
   )
 
   const moveFieldRow: FormContextType['moveFieldRow'] = useCallback(
@@ -655,7 +706,7 @@ export const Form: React.FC<FormProps> = (props) => {
 
       setModified(true)
     },
-    [dispatchFields],
+    [dispatchFields, setModified],
   )
 
   const removeFieldRow: FormContextType['removeFieldRow'] = useCallback(
@@ -664,7 +715,7 @@ export const Form: React.FC<FormProps> = (props) => {
 
       setModified(true)
     },
-    [dispatchFields],
+    [dispatchFields, setModified],
   )
 
   const replaceFieldRow: FormContextType['replaceFieldRow'] = useCallback(
@@ -682,7 +733,7 @@ export const Form: React.FC<FormProps> = (props) => {
 
       setModified(true)
     },
-    [dispatchFields, getDataByPath],
+    [dispatchFields, getDataByPath, setModified],
   )
 
   useEffect(() => {
@@ -763,9 +814,13 @@ export const Form: React.FC<FormProps> = (props) => {
     [formState],
   )
 
-  useEffect(() => {
+  const handleLocaleChange = useEffectEvent(() => {
     contextRef.current = { ...contextRef.current } // triggers rerender of all components that subscribe to form
     setModified(false)
+  })
+
+  useEffect(() => {
+    handleLocaleChange()
   }, [locale])
 
   const classes = [className, baseClass].filter(Boolean).join(' ')

test/form-state/e2e.spec.ts

@@ -3,6 +3,7 @@ import type { PayloadTestSDK } from 'helpers/sdk/index.js'
 import type { FormState } from 'payload'
 
 import { expect, test } from '@playwright/test'
+import { postSlug } from 'folders/shared.js'
 import { assertElementStaysVisible } from 'helpers/e2e/assertElementStaysVisible.js'
 import { assertNetworkRequests } from 'helpers/e2e/assertNetworkRequests.js'
 import { assertRequestBody } from 'helpers/e2e/assertRequestBody.js'
@@ -18,7 +19,7 @@ import * as path from 'path'
 import { wait } from 'payload/shared'
 import { fileURLToPath } from 'url'
 
-import type { Config, Post } from './payload-types.js'
+import type { AutosavePost, Config, Post } from './payload-types.js'
 
 import {
   ensureCompilationIsDone,
@@ -487,13 +488,62 @@ test.describe('Form State', () => {
     )
   })
 
+  test('onChange events are queued even while autosave is in-flight', async () => {
+    const autosavePost = await payload.create({
+      collection: autosavePostsSlug,
+      data: {
+        title: 'Initial Title',
+      },
+    })
+
+    await page.goto(autosavePostsUrl.edit(autosavePost.id))
+    const field = page.locator('#field-title')
+    await expect(field).toBeEnabled()
+
+    const cdpSession = await throttleTest({
+      page,
+      context,
+      delay: 'Slow 3G',
+    })
+
+    try {
+      await assertNetworkRequests(
+        page,
+        `/api/${autosavePostsSlug}/${autosavePost.id}`,
+        async () => {
+          // Type a partial word, then pause for longer than debounce rate to trigger first onChange
+          await field.fill('Tes')
+          await wait(250) // wait for debounce to elapse, but not long enough for the autosave network request to complete
+          // Finish the word, which importantly, should trigger a second onChange while the autosave is still in-flight
+          await field.press('t')
+        },
+        {
+          allowedNumberOfRequests: 2,
+          minimumNumberOfRequests: 2,
+          timeout: 10000,
+        },
+      )
+    } finally {
+      // Ensure throttling is always cleaned up, even if the test fails
+      await cdpSession.send('Network.emulateNetworkConditions', {
+        offline: false,
+        latency: 0,
+        downloadThroughput: -1,
+        uploadThroughput: -1,
+      })
+
+      await cdpSession.detach()
+    }
+  })
+
   describe('Throttled tests', () => {
     let cdpSession: CDPSession
 
     beforeEach(async () => {
       await page.goto(postsUrl.create)
       const field = page.locator('#field-title')
       await field.fill('Test')
+      await expect(field).toBeEnabled()
 
       cdpSession = await throttleTest({
         page,
@@ -580,6 +630,7 @@ test.describe('Form State', () => {
         },
         {
           allowedNumberOfRequests: 2,
+          minimumNumberOfRequests: 2,
           timeout: 10000, // watch network for 10 seconds to allow requests to build up
         },
       )