fix: field schema map paths (#10852)

Continuation of #10638.

Field paths within the schema map are not correct.

For example, an unnamed tab containing a text field should have the
schema path:
- `_index-0.fieldWithinUnnamedTab`

However, within the schema map that path is formatted as:
- `fieldWithinUnnamedTab`

The leading index in the first example _should_ exist, as this field is
nested within another field, regardless of this field being unnamed.
Otherwise, it would be impossible to traverse the schema and lookup this
field.

This discrepancy is not an issue in the admin panel because fields are
_also_ provided the wrong schema paths. They can properly locate their
schema within the schema map because they match despite being incorrect.
Both are wrong and that's why it works.

Here's comprehensive example of how field paths _should_ be formatted:

```ts
{
  // ...
  fields: [
    {
      // path: 'topLevelNamedField'
      // schemaPath: 'topLevelNamedField'
      // indexPath: ''
      name: 'topLevelNamedField',
      type: 'text',
    },
    {
      // path: 'array'
      // schemaPath: 'array'
      // indexPath: ''
      name: 'array',
      type: 'array',
      fields: [
        {
          // path: 'array.[n].fieldWithinArray'
          // schemaPath: 'array.fieldWithinArray'
          // indexPath: ''
          name: 'fieldWithinArray',
          type: 'text',
        },
        {
          // path: 'array.[n].nestedArray'
          // schemaPath: 'array.nestedArray'
          // indexPath: ''
          name: 'nestedArray',
          type: 'array',
          fields: [
            {
              // path: 'array.[n].nestedArray.[n].fieldWithinNestedArray'
              // schemaPath: 'array.nestedArray.fieldWithinNestedArray'
              // indexPath: ''
              name: 'fieldWithinNestedArray',
              type: 'text',
            },
          ],
        },
        {
          // path: 'array.[n]._index-2'
          // schemaPath: 'array._index-2'
          // indexPath: '2'
          type: 'row',
          fields: [
            {
              // path: 'array.[n].fieldWithinRowWithinArray'
              // schemaPath: 'array._index-2.fieldWithinRowWithinArray'
              // indexPath: ''
              name: 'fieldWithinRowWithinArray',
              type: 'text',
            },
          ],
        },
      ],
    },
    {
      // path: '_index-2'
      // schemaPath: '_index-2'
      // indexPath: '2'
      type: 'row',
      fields: [
        {
          // path: 'fieldWithinRow'
          // schemaPath: '_index-2.fieldWithinRow'
          // indexPath: ''
          name: 'fieldWithinRow',
          type: 'text',
        },
      ],
    },
    {
      // path: '_index-3'
      // schemaPath: '_index-3'
      // indexPath: '3'
      type: 'tabs',
      tabs: [
        {
          // path: '_index-3-0'
          // schemaPath: '_index-3-0'
          // indexPath: '3-0'
          label: 'Unnamed Tab',
          fields: [
            {
              // path: 'fieldWithinUnnamedTab'
              // schemaPath: '_index-3-0.fieldWithinUnnamedTab'
              // indexPath: ''
              name: 'fieldWithinUnnamedTab',
              type: 'text',
            },
            {
              // path: '_index-3-0-1'
              // schemaPath: '_index-3-0-1'
              // indexPath: '3-0-1'
              type: 'tabs',
              tabs: [
                {
                  // path: '_index-3-0-1-0'
                  // schemaPath: '_index-3-0-1-0'
                  // indexPath: '3-0-1-0'
                  label: 'Nested Unnamed Tab',
                  fields: [
                    {
                      // path: 'fieldWithinNestedUnnamedTab'
                      // schemaPath: '_index-3-0-1-0.fieldWithinNestedUnnamedTab'
                      // indexPath: ''
                      name: 'fieldWithinNestedUnnamedTab',
                      type: 'text',
                    },
                  ],
                },
              ],
            },
          ],
        },
        {
          // path: 'namedTab'
          // schemaPath: '_index-3.namedTab'
          // indexPath: ''
          label: 'Named Tab',
          name: 'namedTab',
          fields: [
            {
              // path: 'namedTab.fieldWithinNamedTab'
              // schemaPath: '_index-3.namedTab.fieldWithinNamedTab'
              // indexPath: ''
              name: 'fieldWithinNamedTab',
              type: 'text',
            },
          ],
        },
      ],
    },
  ]
}
```

Author: jacobsfletch

.github/workflows/main.yml

@@ -239,6 +239,7 @@ jobs:
           - dashboard
           - joins
           - field-error-states
+          - field-paths
           - fields-relationship
           - fields__collections__Array
           - fields__collections__Blocks

packages/next/src/views/Version/RenderFieldsToDiff/buildVersionFields.tsx

@@ -304,8 +304,8 @@ const buildVersionField = ({
         field: tabAsField,
         index: tabIndex,
         parentIndexPath: indexPath,
-        parentPath,
-        parentSchemaPath,
+        parentPath: path,
+        parentSchemaPath: schemaPath,
       })
 
       let tabFieldsPermissions: SanitizedFieldsPermissions = undefined
@@ -340,11 +340,7 @@ const buildVersionField = ({
           parentIndexPath: isNamedTab ? '' : tabIndexPath,
           parentIsLocalized: parentIsLocalized || tab.localized,
           parentPath: isNamedTab ? tabPath : 'name' in field ? path : parentPath,
-          parentSchemaPath: isNamedTab
-            ? tabSchemaPath
-            : 'name' in field
-              ? schemaPath
-              : parentSchemaPath,
+          parentSchemaPath: tabSchemaPath,
           req,
           selectedLocales,
           versionFromSiblingData: 'name' in tab ? valueFrom?.[tab.name] : valueFrom,
@@ -396,7 +392,7 @@ const buildVersionField = ({
           parentIndexPath: 'name' in field ? '' : indexPath,
           parentIsLocalized: parentIsLocalized || field.localized,
           parentPath: ('name' in field ? path : parentPath) + '.' + i,
-          parentSchemaPath: 'name' in field ? schemaPath : parentSchemaPath,
+          parentSchemaPath: schemaPath,
           req,
           selectedLocales,
           versionFromSiblingData: fromRow,
@@ -424,7 +420,7 @@ const buildVersionField = ({
         parentIndexPath: 'name' in field ? '' : indexPath,
         parentIsLocalized: parentIsLocalized || ('localized' in field && field.localized),
         parentPath: 'name' in field ? path : parentPath,
-        parentSchemaPath: 'name' in field ? schemaPath : parentSchemaPath,
+        parentSchemaPath: schemaPath,
         req,
         selectedLocales,
         versionFromSiblingData: valueFrom as object,
@@ -502,7 +498,7 @@ const buildVersionField = ({
         parentIndexPath: 'name' in field ? '' : indexPath,
         parentIsLocalized: parentIsLocalized || ('localized' in field && field.localized),
         parentPath: ('name' in field ? path : parentPath) + '.' + i,
-        parentSchemaPath: ('name' in field ? schemaPath : parentSchemaPath) + '.' + toBlock.slug,
+        parentSchemaPath: schemaPath + '.' + toBlock.slug,
         req,
         selectedLocales,
         versionFromSiblingData: fromRow,

packages/next/src/views/Version/RenderFieldsToDiff/utilities/getFieldPathsModified.ts

@@ -1,7 +1,7 @@
 import { type SupportedLanguages } from '@payloadcms/translations'
 
 import type { SanitizedDocumentPermissions } from '../../auth/types.js'
-import type { Field, Option, Validate } from '../../fields/config/types.js'
+import type { Field, Option, TabAsField, Validate } from '../../fields/config/types.js'
 import type { TypedLocale } from '../../index.js'
 import type { DocumentPreferences } from '../../preferences/types.js'
 import type { PayloadRequest, SelectType, Where } from '../../types/index.js'
@@ -60,7 +60,7 @@ export type FieldState = {
    * The fieldSchema may be part of the form state if `includeSchema: true` is passed to buildFormState.
    * This will never be in the form state of the client.
    */
-  fieldSchema?: Field
+  fieldSchema?: Field | TabAsField
   filterOptions?: FilterOptionsResult
   initialValue?: unknown
   /**

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

@@ -1982,7 +1982,7 @@ export type FieldWithManyClient = RelationshipFieldClient | SelectFieldClient
 export type FieldWithMaxDepth = RelationshipField | UploadField
 export type FieldWithMaxDepthClient = JoinFieldClient | RelationshipFieldClient | UploadFieldClient
 
-export function fieldHasSubFields<TField extends ClientField | Field>(
+export function fieldHasSubFields<TField extends ClientField | Field | TabAsField>(
   field: TField,
 ): field is TField & (TField extends ClientField ? FieldWithSubFieldsClient : FieldWithSubFields) {
   return (

packages/payload/src/fields/config/types.ts

@@ -1,10 +1,14 @@
+import type { ClientTab } from '../admin/types.js'
 import type { ClientField, Field, Tab, TabAsFieldClient } from './config/types.js'
 
 type Args = {
-  field: ClientField | Field | Tab | TabAsFieldClient
+  field: ClientField | ClientTab | Field | Tab | TabAsFieldClient
   index: number
   parentIndexPath: string
-  parentPath: string
+  /**
+   * Needed to generate data paths. Omit if you only need schema paths, e.g. within field schema maps.
+   */
+  parentPath?: string
   parentSchemaPath: string
 }
 
@@ -29,45 +33,19 @@ export function getFieldPaths({
   field,
   index,
   parentIndexPath,
-  parentPath,
-  parentSchemaPath,
-}: Args): FieldPaths {
-  if ('name' in field) {
-    return {
-      indexPath: `${parentIndexPath ? parentIndexPath + '-' : ''}${index}`,
-      path: `${parentPath ? parentPath + '.' : ''}${field.name}`,
-      schemaPath: `${parentSchemaPath ? parentSchemaPath + '.' : ''}${field.name}`,
-    }
-  }
-
-  const indexSuffix = `_index-${`${parentIndexPath ? parentIndexPath + '-' : ''}${index}`}`
-
-  return {
-    indexPath: `${parentIndexPath ? parentIndexPath + '-' : ''}${index}`,
-    path: `${parentPath ? parentPath + '.' : ''}${indexSuffix}`,
-    schemaPath: `${parentSchemaPath ? parentSchemaPath + '.' : ''}${indexSuffix}`,
-  }
-}
-
-/**
- * @deprecated - will be removed in 4.0. Use `getFieldPaths` instead.
- */
-export function getFieldPathsModified({
-  field,
-  index,
-  parentIndexPath,
-  parentPath,
+  parentPath = '',
   parentSchemaPath,
 }: Args): FieldPaths {
   const parentPathSegments = parentPath.split('.')
 
-  const parentIsUnnamed = parentPathSegments[parentPathSegments.length - 1]!.startsWith('_index-')
+  const parentPathIsUnnamed =
+    parentPathSegments?.[parentPathSegments.length - 1]?.startsWith('_index-')
 
-  const parentWithoutIndex = parentIsUnnamed
+  const parentWithoutIndex = parentPathIsUnnamed
     ? parentPathSegments.slice(0, -1).join('.')
     : parentPath
 
-  const parentPathToUse = parentIsUnnamed ? parentWithoutIndex : parentPath
+  const parentPathToUse = parentPathIsUnnamed ? parentWithoutIndex : parentPath
 
   if ('name' in field) {
     return {
@@ -79,9 +57,16 @@ export function getFieldPathsModified({
 
   const indexSuffix = `_index-${`${parentIndexPath ? parentIndexPath + '-' : ''}${index}`}`
 
+  const parentSchemaPathSegments = parentSchemaPath.split('.')
+
+  const parentSchemaPathIsUnnamed =
+    parentSchemaPathSegments?.[parentSchemaPathSegments.length - 1]?.startsWith('_index-')
+
   return {
     indexPath: `${parentIndexPath ? parentIndexPath + '-' : ''}${index}`,
     path: `${parentPathToUse ? parentPathToUse + '.' : ''}${indexSuffix}`,
-    schemaPath: `${!parentIsUnnamed && parentSchemaPath ? parentSchemaPath + '.' : ''}${indexSuffix}`,
+    schemaPath: parentSchemaPathIsUnnamed
+      ? `${parentSchemaPath}-${index}`
+      : `${parentSchemaPath ? parentSchemaPath + '.' : ''}${indexSuffix}`,
   }
 }

packages/payload/src/fields/getFieldPaths.ts

@@ -7,7 +7,7 @@ import type { Block, Field, TabAsField } from '../../config/types.js'
 
 import { MissingEditorProp } from '../../../errors/index.js'
 import { fieldAffectsData, tabHasName } from '../../config/types.js'
-import { getFieldPathsModified as getFieldPaths } from '../../getFieldPaths.js'
+import { getFieldPaths } from '../../getFieldPaths.js'
 import { traverseFields } from './traverseFields.js'
 
 type Args = {

packages/payload/src/fields/hooks/afterChange/promise.ts

@@ -17,7 +17,7 @@ import { getBlockSelect } from '../../../utilities/getBlockSelect.js'
 import { stripUnselectedFields } from '../../../utilities/stripUnselectedFields.js'
 import { fieldAffectsData, fieldShouldBeLocalized, tabHasName } from '../../config/types.js'
 import { getDefaultValue } from '../../getDefaultValue.js'
-import { getFieldPathsModified as getFieldPaths } from '../../getFieldPaths.js'
+import { getFieldPaths } from '../../getFieldPaths.js'
 import { relationshipPopulationPromise } from './relationshipPopulationPromise.js'
 import { traverseFields } from './traverseFields.js'
 import { virtualFieldPopulationPromise } from './virtualFieldPopulationPromise.js'

packages/payload/src/fields/hooks/afterRead/promise.ts

@@ -10,7 +10,7 @@ import { type RequestContext, validateBlocksFilterOptions } from '../../../index
 import { deepMergeWithSourceArrays } from '../../../utilities/deepMerge.js'
 import { getTranslatedLabel } from '../../../utilities/getTranslatedLabel.js'
 import { fieldAffectsData, fieldShouldBeLocalized, tabHasName } from '../../config/types.js'
-import { getFieldPathsModified as getFieldPaths } from '../../getFieldPaths.js'
+import { getFieldPaths } from '../../getFieldPaths.js'
 import { getExistingRowDoc } from './getExistingRowDoc.js'
 import { traverseFields } from './traverseFields.js'
 

packages/payload/src/fields/hooks/beforeChange/promise.ts

@@ -4,7 +4,7 @@ import type { JsonObject, PayloadRequest } from '../../../types/index.js'
 import type { Block, Field, FieldHookArgs, TabAsField } from '../../config/types.js'
 
 import { fieldAffectsData, fieldShouldBeLocalized } from '../../config/types.js'
-import { getFieldPathsModified as getFieldPaths } from '../../getFieldPaths.js'
+import { getFieldPaths } from '../../getFieldPaths.js'
 import { traverseFields } from './traverseFields.js'
 
 type Args<T> = {