feat: relationship sortOptions property (#4301)

* feat: adds sortOptions property to relationship field

* chore: fix lexical int tests

* feat: simplifies logic & updates joi schema definition

* feat: revert to default when searching in relationship select

* fix types and joi schema

* type adjustments

---------

Co-authored-by: Alessio Gravili <alessio@bonfireleads.com>
Co-authored-by: Jarrod Flesch <jarrodmflesch@gmail.com>

packages/payload/src/admin/components/forms/field-types/Relationship/index.tsx

@@ -40,13 +40,14 @@ const Relationship: React.FC<Props> = (props) => {
     admin: {
       allowCreate = true,
       className,
+      components: { Error, Label } = {},
       condition,
       description,
       isSortable = true,
       readOnly,
+      sortOptions,
       style,
       width,
-      components: { Error, Label } = {},
     } = {},
     filterOptions,
     hasMany,
@@ -139,7 +140,14 @@ const Relationship: React.FC<Props> = (props) => {
 
           if (resultsFetched < 10) {
             const collection = collections.find((coll) => coll.slug === relation)
-            const fieldToSearch = collection?.admin?.useAsTitle || 'id'
+            let fieldToSearch = collection?.defaultSort || collection?.admin?.useAsTitle || 'id'
+            if (!searchArg) {
+              if (typeof sortOptions === 'string') {
+                fieldToSearch = sortOptions
+              } else if (sortOptions?.[relation]) {
+                fieldToSearch = sortOptions[relation]
+              }
+            }
 
             const query: {
               [key: string]: unknown
@@ -236,6 +244,7 @@ const Relationship: React.FC<Props> = (props) => {
       locale,
       filterOptionsResult,
       serverURL,
+      sortOptions,
       api,
       i18n,
       config,
@@ -252,7 +261,7 @@ const Relationship: React.FC<Props> = (props) => {
     (searchArg: string, valueArg: Value | Value[]) => {
       if (search !== searchArg) {
         setLastLoadedPage({})
-        updateSearch(searchArg, valueArg)
+        updateSearch(searchArg, valueArg, searchArg !== '')
       }
     },
     [search, updateSearch],

packages/payload/src/exports/types.ts

@@ -80,6 +80,7 @@ export type {
   Option,
   OptionObject,
   PointField,
+  PolymorphicRelationshipField,
   RadioField,
   RelationshipField,
   RelationshipValue,
@@ -87,6 +88,7 @@ export type {
   RowAdmin,
   RowField,
   SelectField,
+  SingleRelationshipField,
   Tab,
   TabAsField,
   TabsAdmin,

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

@@ -366,6 +366,11 @@ export const relationship = baseField.keys({
       Label: componentSchema,
     }),
     isSortable: joi.boolean().default(false),
+    sortOptions: joi.alternatives().conditional(joi.ref('...relationTo'), {
+      is: joi.string(),
+      otherwise: joi.object().pattern(joi.string(), joi.string()),
+      then: joi.string(),
+    }),
   }),
   defaultValue: joi.alternatives().try(joi.func()),
   filterOptions: joi.alternatives().try(joi.object(), joi.func()),

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

@@ -430,19 +430,10 @@ export type SelectField = FieldBase & {
   type: 'select'
 }
 
-export type RelationshipField = FieldBase & {
-  admin?: Admin & {
-    allowCreate?: boolean
-    components?: {
-      Error?: React.ComponentType<ErrorProps>
-      Label?: React.ComponentType<LabelProps>
-    }
-    isSortable?: boolean
-  }
+type SharedRelationshipProperties = FieldBase & {
   filterOptions?: FilterOptions
   hasMany?: boolean
   maxDepth?: number
-  relationTo: string | string[]
   type: 'relationship'
 } & (
     | {
@@ -473,6 +464,28 @@ export type RelationshipField = FieldBase & {
       }
   )
 
+type RelationshipAdmin = Admin & {
+  allowCreate?: boolean
+  components?: {
+    Error?: React.ComponentType<ErrorProps>
+    Label?: React.ComponentType<LabelProps>
+  }
+  isSortable?: boolean
+}
+export type PolymorphicRelationshipField = SharedRelationshipProperties & {
+  admin?: RelationshipAdmin & {
+    sortOptions?: { [collectionSlug: string]: string }
+  }
+  relationTo: string[]
+}
+export type SingleRelationshipField = SharedRelationshipProperties & {
+  admin?: RelationshipAdmin & {
+    sortOptions?: string
+  }
+  relationTo: string
+}
+export type RelationshipField = PolymorphicRelationshipField | SingleRelationshipField
+
 export type ValueWithRelation = {
   relationTo: string
   value: number | string

packages/plugin-nested-docs/src/fields/parent.ts

@@ -1,13 +1,13 @@
-import type { RelationshipField } from 'payload/types'
+import type { SingleRelationshipField } from 'payload/types'
 
 const createParentField = (
   relationTo: string,
   overrides?: Partial<
-    RelationshipField & {
+    SingleRelationshipField & {
       hasMany: false
     }
   >,
-): RelationshipField => ({
+): SingleRelationshipField => ({
   name: 'parent',
   relationTo,
   type: 'relationship',