fix: threads path and value through field desc fns again and defers c…

…lient-side rendering
payloadcms · Nov 17, 2024 · 18ccfe2 · 18ccfe2
1 parent c9040b6
commit 18ccfe2
Show file tree

Hide file tree

Showing 4 changed files with 38 additions and 26 deletions.
diff --git a/docs/admin/fields.mdx b/docs/admin/fields.mdx
@@ -93,7 +93,7 @@ export const MyCollectionConfig: SanitizedCollectionConfig = {
 
 #### Description Functions
 
-Custom Descriptions can also be defined as a function. Description Functions are executed on the server and can be used to format simple descriptions based on the user's current [Locale](../configuration/localization).
+Custom Descriptions can also be defined as a function. Description Functions are executed on the server and can be used to format simple descriptions based on the user's current [Locale](../configuration/localization), document data, etc.
 
 To easily add a Description Function to a field, set the `admin.description` property to a _function_ in your [Field Config](../fields/overview):
 
@@ -120,6 +120,14 @@ All Description Functions receive the following arguments:
 | Argument       | Description                                                      |
 | -------------- | ---------------------------------------------------------------- |
 | **`t`**        | The `t` function used to internationalize the Admin Panel. [More details](../configuration/i18n) |
+| **`path`**     | A string representing the direct, dynamic path to the field at runtime, i.e. `myGroup.myArray.0.myField`. |
+| **`data`**     | The initial data of the document. |
+| **`value`**    | The value of the field at render-time. |
+
+<Banner type="info">
+  <strong>Note:</strong>
+  If you need to subscribe to live changes within your form, use must use a Description Component instead. [More details](#description).
+</Banner>
 
 ## Conditional Logic
 

diff --git a/packages/payload/src/admin/forms/Description.ts b/packages/payload/src/admin/forms/Description.ts
@@ -1,8 +1,18 @@
-import type { LabelFunction, ServerProps } from '../../config/types.js'
+import type { TFunction } from '@payloadcms/translations'
+
+import type { ServerProps } from '../../config/types.js'
 import type { Field } from '../../fields/config/types.js'
 import type { ClientFieldWithOptionalType } from './Field.js'
-
-export type DescriptionFunction = LabelFunction
+import type { Data } from './Form.js'
+
+export type DescriptionFunction = <T = unknown>({
+  t,
+}: {
+  data: Data
+  path: string
+  t: TFunction
+  value?: T
+}) => string
 
 export type FieldDescriptionClientComponent<
   TFieldClient extends ClientFieldWithOptionalType = ClientFieldWithOptionalType,

diff --git a/packages/payload/src/fields/config/client.ts b/packages/payload/src/fields/config/client.ts
@@ -274,15 +274,10 @@ export const createClientField = ({
   } & ClientField
 
   if (incomingField.admin && 'description' in incomingField.admin) {
-    if (
-      typeof incomingField.admin?.description === 'string' ||
-      typeof incomingField.admin?.description === 'object'
-    ) {
+    if (typeof incomingField.admin?.description === 'function') {
+      delete (clientField as FieldWithDescription).admin.description
+    } else {
       ;(clientField as FieldWithDescription).admin.description = incomingField.admin.description
-    } else if (typeof incomingField.admin?.description === 'function') {
-      ;(clientField as FieldWithDescription).admin.description = incomingField.admin?.description({
-        t: i18n.t,
-      })
     }
   }
 

diff --git a/packages/ui/src/forms/fieldSchemasToFormState/renderField.tsx b/packages/ui/src/forms/fieldSchemasToFormState/renderField.tsx
@@ -202,20 +202,19 @@ export const renderField: RenderFieldMethod = ({
 
   if (fieldConfig.admin) {
     if ('description' in fieldConfig.admin) {
-      // @TODO move this to client, only render if it is a function
-      fieldState.customComponents.Description = (
-        <FieldDescription
-          description={
-            typeof fieldConfig.admin?.description === 'string' ||
-            typeof fieldConfig.admin?.description === 'object'
-              ? fieldConfig.admin.description
-              : typeof fieldConfig.admin?.description === 'function'
-                ? fieldConfig.admin?.description({ t: req.i18n.t })
-                : ''
-          }
-          path={path}
-        />
-      )
+      if (typeof fieldConfig.admin?.description === 'function') {
+        fieldState.customComponents.Description = (
+          <FieldDescription
+            description={fieldConfig.admin?.description({
+              data,
+              path,
+              t: req.i18n.t,
+              value: 'name' in fieldConfig ? formState[fieldConfig.name] : undefined,
+            })}
+            path={path}
+          />
+        )
+      }
     }
 
     if (fieldConfig.admin?.components) {