fix: server component readonly state issues with document locking (#13878)

### What?

Fixed two bugs with readonly state for server-rendered components (like
richtext fields and custom server fields):

1. Server components remained readonly after a user took over a locked
document
2. Server components were not readonly when viewing in "read only" mode
until page refresh

### Why?

Both issues stemmed from server-rendered components using their initial
readonly state that was baked in during server-side rendering, rather
than respecting dynamic readonly state changes:

1. **Takeover bug**: When a user took over a locked document,
client-side readonly state was updated but server components continued
using their initial readonly state because the server-side state wasn't
refreshed properly.

2. **Read-only view bug**: When entering "read only" mode, server
components weren't immediately updated to reflect the new readonly state
without a page refresh.

The root cause was that server-side `buildFormState` was called with
`readOnly: isLocked` during initial render, and individual field
components used this initial state rather than respecting dynamic
document-level readonly changes.

### How?

1. **Fixed race condition in `handleTakeOver`**: Made the function async
and await the `updateDocumentEditor` call before calling
`clearRouteCache()` to ensure the database is updated before page reload

2. **Improved editor comparison in `getIsLocked`**: Used `extractID()`
helper to properly compare editor IDs when the editor might be a
reference object

3. **Ensured cache clearing for all takeover scenarios**: Call
`clearRouteCache()` for both DocumentLocked modal and DocumentControls
takeovers to refresh server-side state

4. **Added Form key to force re-render**: Added `key={isLocked}` to the
Form component so it re-renders when the lock state changes, ensuring
all child components get fresh readonly state for both takeover and
read-only view scenarios


---
- To see the specific tasks where the Asana app for GitHub is being
used, see below:
  - https://app.asana.com/0/0/1211373627247885

Author: PatrikKozak

packages/next/src/views/Document/getIsLocked.ts

@@ -7,6 +7,7 @@ import type {
 } from 'payload'
 
 import { sanitizeID } from '@payloadcms/ui/shared'
+import { extractID } from 'payload/shared'
 
 type Args = {
   collectionConfig?: SanitizedCollectionConfig
@@ -93,12 +94,12 @@ export const getIsLocked = async ({
   })
 
   if (docs.length > 0) {
-    const newEditor = docs[0].user?.value
+    const currentEditor = docs[0].user?.value
     const lastUpdateTime = new Date(docs[0].updatedAt).getTime()
 
-    if (newEditor?.id !== req.user.id) {
+    if (extractID(currentEditor) !== req.user.id) {
       return {
-        currentEditor: newEditor,
+        currentEditor,
         isLocked: true,
         lastUpdateTime,
       }

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

@@ -3,6 +3,7 @@ import type { ClientUser } from 'payload'
 
 import React, { useEffect } from 'react'
 
+import { useRouteCache } from '../../providers/RouteCache/index.js'
 import { useRouteTransition } from '../../providers/RouteTransition/index.js'
 import { useTranslation } from '../../providers/Translation/index.js'
 import { isClientUserObject } from '../../utilities/isClientUserObject.js'
@@ -38,6 +39,7 @@ export const DocumentLocked: React.FC<{
 }> = ({ handleGoBack, isActive, onReadOnly, onTakeOver, updatedAt, user }) => {
   const { closeModal, openModal } = useModal()
   const { t } = useTranslation()
+  const { clearRouteCache } = useRouteCache()
   const { startRouteTransition } = useRouteTransition()
 
   useEffect(() => {
@@ -86,6 +88,7 @@ export const DocumentLocked: React.FC<{
             onClick={() => {
               onReadOnly()
               closeModal(modalSlug)
+              clearRouteCache()
             }}
             size="large"
           >
@@ -95,7 +98,7 @@ export const DocumentLocked: React.FC<{
             buttonStyle="primary"
             id={`${modalSlug}-take-over`}
             onClick={() => {
-              void onTakeOver()
+              onTakeOver()
               closeModal(modalSlug)
             }}
             size="large"

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

@@ -1,6 +1,7 @@
 'use client'
 import React, { useEffect } from 'react'
 
+import { useRouteCache } from '../../providers/RouteCache/index.js'
 import { useRouteTransition } from '../../providers/RouteTransition/index.js'
 import { useTranslation } from '../../providers/Translation/index.js'
 import { Button } from '../Button/index.js'
@@ -19,6 +20,7 @@ export const DocumentTakeOver: React.FC<{
   const { closeModal, openModal } = useModal()
   const { t } = useTranslation()
   const { startRouteTransition } = useRouteTransition()
+  const { clearRouteCache } = useRouteCache()
 
   useEffect(() => {
     if (isActive) {
@@ -52,6 +54,7 @@ export const DocumentTakeOver: React.FC<{
             onClick={() => {
               onReadOnly()
               closeModal(modalSlug)
+              clearRouteCache()
             }}
             size="large"
           >

packages/ui/src/utilities/handleTakeOver.tsx

@@ -1,32 +1,47 @@
 import type { ClientUser } from 'payload'
 
-export const handleTakeOver = (
-  id: number | string,
-  collectionSlug: string,
-  globalSlug: string,
-  user: ClientUser | number | string,
-  isWithinDoc: boolean,
-  updateDocumentEditor: (
-    docID: number | string,
-    slug: string,
-    user: ClientUser | number | string,
-  ) => Promise<void>,
-  setCurrentEditor: (value: React.SetStateAction<ClientUser | number | string>) => void,
+export interface HandleTakeOverParams {
+  clearRouteCache?: () => void
+  collectionSlug?: string
   documentLockStateRef: React.RefObject<{
     hasShownLockedModal: boolean
     isLocked: boolean
     user: ClientUser | number | string
-  }>,
-  isLockingEnabled: boolean,
-  setIsReadOnlyForIncomingUser?: (value: React.SetStateAction<boolean>) => void,
-): void => {
+  }>
+  globalSlug?: string
+  id: number | string
+  isLockingEnabled: boolean
+  isWithinDoc: boolean
+  setCurrentEditor: (value: React.SetStateAction<ClientUser | number | string>) => void
+  setIsReadOnlyForIncomingUser?: (value: React.SetStateAction<boolean>) => void
+  updateDocumentEditor: (
+    docID: number | string,
+    slug: string,
+    user: ClientUser | number | string,
+  ) => Promise<void>
+  user: ClientUser | number | string
+}
+
+export const handleTakeOver = async ({
+  id,
+  clearRouteCache,
+  collectionSlug,
+  documentLockStateRef,
+  globalSlug,
+  isLockingEnabled,
+  isWithinDoc,
+  setCurrentEditor,
+  setIsReadOnlyForIncomingUser,
+  updateDocumentEditor,
+  user,
+}: HandleTakeOverParams): Promise<void> => {
   if (!isLockingEnabled) {
     return
   }
 
   try {
     // Call updateDocumentEditor to update the document's owner to the current user
-    void updateDocumentEditor(id, collectionSlug ?? globalSlug, user)
+    await updateDocumentEditor(id, collectionSlug ?? globalSlug, user)
 
     if (!isWithinDoc) {
       documentLockStateRef.current.hasShownLockedModal = true
@@ -44,6 +59,11 @@ export const handleTakeOver = (
     if (isWithinDoc && setIsReadOnlyForIncomingUser) {
       setIsReadOnlyForIncomingUser(false)
     }
+
+    // Need to clear the route cache to refresh the page and update readOnly state for server rendered components
+    if (clearRouteCache) {
+      clearRouteCache()
+    }
   } catch (error) {
     // eslint-disable-next-line no-console
     console.error('Error during document takeover:', error)

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

@@ -28,6 +28,7 @@ import { useDocumentInfo } from '../../providers/DocumentInfo/index.js'
 import { useEditDepth } from '../../providers/EditDepth/index.js'
 import { useLivePreviewContext } from '../../providers/LivePreview/context.js'
 import { OperationProvider } from '../../providers/Operation/index.js'
+import { useRouteCache } from '../../providers/RouteCache/index.js'
 import { useRouteTransition } from '../../providers/RouteTransition/index.js'
 import { useServerFunctions } from '../../providers/ServerFunctions/index.js'
 import { UploadControlsProvider } from '../../providers/UploadControls/index.js'
@@ -87,6 +88,7 @@ export function DefaultEditView({
     initialState,
     isEditing,
     isInitializing,
+    isLocked,
     isTrashed,
     lastUpdateTime,
     redirectAfterCreate,
@@ -134,6 +136,7 @@ export function DefaultEditView({
   const { resetUploadEdits } = useUploadEdits()
   const { getFormState } = useServerFunctions()
   const { startRouteTransition } = useRouteTransition()
+  const { clearRouteCache } = useRouteCache()
   const {
     isLivePreviewEnabled,
     isLivePreviewing,
@@ -511,6 +514,7 @@ export function DefaultEditView({
           initialState={!isInitializing && initialState}
           isDocumentForm={true}
           isInitializing={isInitializing}
+          key={`${isLocked}`}
           method={id ? 'PATCH' : 'POST'}
           onChange={[onChange]}
           onSuccess={onSave}
@@ -527,17 +531,18 @@ export function DefaultEditView({
                 setShowTakeOverModal(false)
               }}
               onTakeOver={() =>
-                handleTakeOver(
+                handleTakeOver({
                   id,
+                  clearRouteCache,
                   collectionSlug,
+                  documentLockStateRef: documentLockState,
                   globalSlug,
-                  user,
-                  false,
-                  updateDocumentEditor,
-                  setCurrentEditor,
-                  documentLockState,
                   isLockingEnabled,
-                )
+                  isWithinDoc: false,
+                  setCurrentEditor,
+                  updateDocumentEditor,
+                  user,
+                })
               }
               updatedAt={lastUpdateTime}
               user={currentEditor}
@@ -597,18 +602,19 @@ export function DefaultEditView({
             onRestore={onRestore}
             onSave={onSave}
             onTakeOver={() =>
-              handleTakeOver(
+              handleTakeOver({
                 id,
+                clearRouteCache,
                 collectionSlug,
+                documentLockStateRef: documentLockState,
                 globalSlug,
-                user,
-                true,
-                updateDocumentEditor,
-                setCurrentEditor,
-                documentLockState,
                 isLockingEnabled,
+                isWithinDoc: true,
+                setCurrentEditor,
                 setIsReadOnlyForIncomingUser,
-              )
+                updateDocumentEditor,
+                user,
+              })
             }
             permissions={docPermissions}
             readOnlyForIncomingUser={isReadOnlyForIncomingUser}

test/locked-documents/collections/Posts/fields/CustomTextFieldServer.tsx

@@ -0,0 +1,22 @@
+import type { TextFieldServerComponent } from 'payload'
+import type React from 'react'
+
+import { TextField } from '@payloadcms/ui'
+
+export const CustomTextFieldServer: TextFieldServerComponent = ({
+  clientField,
+  path,
+  permissions,
+  readOnly,
+  schemaPath,
+}) => {
+  return (
+    <TextField
+      field={clientField}
+      path={path}
+      permissions={permissions}
+      readOnly={readOnly}
+      schemaPath={schemaPath}
+    />
+  )
+}

test/locked-documents/collections/ServerComponents/index.ts

@@ -0,0 +1,25 @@
+import type { CollectionConfig } from 'payload'
+
+export const serverComponentsSlug = 'server-components'
+
+export const ServerComponentsCollection: CollectionConfig = {
+  slug: serverComponentsSlug,
+  admin: {
+    useAsTitle: 'customTextServer',
+  },
+  fields: [
+    {
+      name: 'customTextServer',
+      type: 'text',
+      admin: {
+        components: {
+          Field: '/collections/Posts/fields/CustomTextFieldServer.tsx#CustomTextFieldServer',
+        },
+      },
+    },
+    {
+      name: 'richText',
+      type: 'richText',
+    },
+  ],
+}

test/locked-documents/config.ts

@@ -4,6 +4,7 @@ import path from 'path'
 import { buildConfigWithDefaults } from '../buildConfigWithDefaults.js'
 import { PagesCollection } from './collections/Pages/index.js'
 import { PostsCollection } from './collections/Posts/index.js'
+import { ServerComponentsCollection } from './collections/ServerComponents/index.js'
 import { TestsCollection } from './collections/Tests/index.js'
 import { Users } from './collections/Users/index.js'
 import { AdminGlobal } from './globals/Admin/index.js'
@@ -19,7 +20,13 @@ export default buildConfigWithDefaults({
       baseDir: path.resolve(dirname),
     },
   },
-  collections: [PagesCollection, PostsCollection, TestsCollection, Users],
+  collections: [
+    PagesCollection,
+    PostsCollection,
+    ServerComponentsCollection,
+    TestsCollection,
+    Users,
+  ],
   globals: [AdminGlobal, MenuGlobal],
   onInit: async (payload) => {
     if (process.env.SEED_IN_CONFIG_ONINIT !== 'false') {