fix(ui): automatically subscribes custom fields to conditional logic (#9928)

Currently, custom components do not respect `admin.condition` unless
manually wrapped with the `withCondition` HOC, like all default fields
currently do. This should not be a requirement of component authors.
Instead, we can automatically detect custom client and server fields and
wrap them with the underlying `WatchCondition` component which will
subscribe to the `passesCondition` property within client-side form
state.

For my future self: there are potentially multiple instances where
fields subscribe to conditions duplicately, such as when rendering a
default Payload field within a custom field component. This was always a
problem and it is non-breaking, but needs to be reevaluated and removed
in the future for performance. Only the default fields that Payload
renders client-side need to subscribe to field conditions in this way.
When importing a Payload field into your custom field component, for
example, it should not include the HOC, because custom components now
watch conditions themselves.

Author: jacobsfletch

packages/payload/src/queues/localAPI.ts

@@ -22,18 +22,18 @@ export const getJobsLocalAPI = (payload: Payload) => ({
           req?: PayloadRequest
           // TTaskOrWorkflowlug with keyof TypedJobs['workflows'] removed:
           task: TTaskOrWorkflowSlug extends keyof TypedJobs['tasks'] ? TTaskOrWorkflowSlug : never
-          workflow?: never
           waitUntil?: Date
+          workflow?: never
         }
       | {
           input: TypedJobs['workflows'][TTaskOrWorkflowSlug]['input']
           queue?: string
           req?: PayloadRequest
           task?: never
+          waitUntil?: Date
           workflow: TTaskOrWorkflowSlug extends keyof TypedJobs['workflows']
             ? TTaskOrWorkflowSlug
             : never
-          waitUntil?: Date
         },
   ): Promise<
     TTaskOrWorkflowSlug extends keyof TypedJobs['workflows']
@@ -60,8 +60,8 @@ export const getJobsLocalAPI = (payload: Payload) => ({
         input: args.input,
         queue,
         taskSlug: 'task' in args ? args.task : undefined,
-        workflowSlug: 'workflow' in args ? args.workflow : undefined,
         waitUntil: args.waitUntil?.toISOString() ?? undefined,
+        workflowSlug: 'workflow' in args ? args.workflow : undefined,
       } as BaseJob,
       req: args.req,
     })) as TTaskOrWorkflowSlug extends keyof TypedJobs['workflows']

packages/richtext-lexical/src/field/Field.tsx

@@ -9,7 +9,6 @@ import {
   RenderCustomComponent,
   useEditDepth,
   useField,
-  withCondition,
 } from '@payloadcms/ui'
 import { mergeFieldStyles } from '@payloadcms/ui/shared'
 import React, { useCallback, useMemo } from 'react'
@@ -143,4 +142,4 @@ function fallbackRender({ error }: { error: Error }) {
   )
 }
 
-export const RichText: typeof RichTextComponent = withCondition(RichTextComponent)
+export const RichText: typeof RichTextComponent = RichTextComponent

packages/richtext-slate/src/field/RichText.tsx

@@ -14,7 +14,6 @@ import {
   useEditDepth,
   useField,
   useTranslation,
-  withCondition,
 } from '@payloadcms/ui'
 import { mergeFieldStyles } from '@payloadcms/ui/shared'
 import { isHotkey } from 'is-hotkey'
@@ -459,4 +458,4 @@ const RichTextField: React.FC<LoadedSlateFieldProps> = (props) => {
   )
 }
 
-export const RichText = withCondition(RichTextField)
+export const RichText = RichTextField

packages/ui/src/exports/client/index.ts

@@ -196,6 +196,7 @@ export { useField } from '../../forms/useField/index.js'
 export type { FieldType, Options } from '../../forms/useField/types.js'
 
 export { withCondition } from '../../forms/withCondition/index.js'
+export { WatchCondition } from '../../forms/withCondition/WatchCondition.js'
 
 // graphics
 export { Account } from '../../graphics/Account/index.js'

packages/ui/src/forms/RenderFields/RenderField.tsx

@@ -51,10 +51,10 @@ export function RenderField({
   readOnly,
   schemaPath,
 }: RenderFieldProps) {
-  const Field = useFormFields(([fields]) => fields && fields?.[path]?.customComponents?.Field)
+  const CustomField = useFormFields(([fields]) => fields && fields?.[path]?.customComponents?.Field)
 
-  if (Field !== undefined) {
-    return Field || null
+  if (CustomField !== undefined) {
+    return CustomField || null
   }
 
   const baseFieldProps: Pick<ClientComponentProps, 'forceRender' | 'readOnly' | 'schemaPath'> = {

packages/ui/src/forms/fieldSchemasToFormState/renderField.tsx

@@ -9,7 +9,7 @@ import type { RenderFieldMethod } from './types.js'
 import { RenderServerComponent } from '../../elements/RenderServerComponent/index.js'
 
 // eslint-disable-next-line payload/no-imports-from-exports-dir -- need this to reference already existing bundle. Otherwise, bundle size increases., payload/no-imports-from-exports-dir
-import { FieldDescription } from '../../exports/client/index.js'
+import { FieldDescription, WatchCondition } from '../../exports/client/index.js'
 
 const defaultUIFieldComponentKeys: Array<'Cell' | 'Description' | 'Field' | 'Filter'> = [
   'Cell',
@@ -135,12 +135,16 @@ export const renderField: RenderFieldMethod = ({
         fieldConfig.admin.components = {}
       }
 
-      fieldState.customComponents.Field = RenderServerComponent({
-        clientProps,
-        Component: fieldConfig.editor.FieldComponent,
-        importMap: req.payload.importMap,
-        serverProps,
-      })
+      fieldState.customComponents.Field = (
+        <WatchCondition path={path}>
+          {RenderServerComponent({
+            clientProps,
+            Component: fieldConfig.editor.FieldComponent,
+            importMap: req.payload.importMap,
+            serverProps,
+          })}
+        </WatchCondition>
+      )
 
       break
     }
@@ -236,13 +240,17 @@ export const renderField: RenderFieldMethod = ({
       }
 
       if ('Field' in fieldConfig.admin.components) {
-        fieldState.customComponents.Field = RenderServerComponent({
-          clientProps,
-          Component: fieldConfig.admin.components.Field,
-          importMap: req.payload.importMap,
-          key: 'field.admin.components.Field',
-          serverProps,
-        })
+        fieldState.customComponents.Field = (
+          <WatchCondition path={path}>
+            {RenderServerComponent({
+              clientProps,
+              Component: fieldConfig.admin.components.Field,
+              importMap: req.payload.importMap,
+              key: 'field.admin.components.Field',
+              serverProps,
+            })}
+          </WatchCondition>
+        )
       }
     }
   }

packages/ui/src/forms/withCondition/WatchCondition.tsx

@@ -6,7 +6,6 @@ import { useFormFields } from '../Form/context.js'
 
 export const WatchCondition: React.FC<{
   children: React.ReactNode
-  indexPath: string
   path: string
 }> = (props) => {
   const { children, path } = props

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

@@ -10,10 +10,10 @@ export const withCondition = <P extends MarkOptional<FieldPaths, 'indexPath' | '
   Field: React.ComponentType<P>,
 ): React.FC<P> => {
   const CheckForCondition: React.FC<P> = (props) => {
-    const { indexPath, path } = props
+    const { path } = props
 
     return (
-      <WatchCondition indexPath={indexPath} path={path}>
+      <WatchCondition path={path}>
         <Field {...props} />
       </WatchCondition>
     )

templates/_template/.vscode/settings.json

@@ -36,5 +36,5 @@
     "editor.codeActionsOnSave": {
       "source.fixAll.eslint": "explicit"
     }
-  },
+  }
 }

templates/_template/package.json

@@ -28,12 +28,12 @@
     "sharp": "0.32.6"
   },
   "devDependencies": {
+    "@eslint/eslintrc": "^3.2.0",
     "@types/node": "^22.5.4",
     "@types/react": "19.0.1",
     "@types/react-dom": "19.0.1",
     "eslint": "^9.16.0",
     "eslint-config-next": "15.1.0",
-    "@eslint/eslintrc": "^3.2.0",
     "prettier": "^3.4.2",
     "typescript": "5.7.2"
   },