feat(core): Incoming references form decoration

dev/test-studio/components/IncomingReferencesActions.tsx

@@ -0,0 +1,30 @@
+import {TrashIcon} from '@sanity/icons'
+import {type IncomingReferenceAction} from '@sanity/types'
+import {getDraftId} from 'sanity'
+
+export const RemoveReferenceAction: IncomingReferenceAction = ({document, getClient}) => {
+  const client = getClient({apiVersion: '2025-10-01'})
+  const handleRemoveReference = async () => {
+    if (document._type === 'author') {
+      await client.createOrReplace({
+        ...document,
+        _id: getDraftId(document._id),
+        bestFriend: undefined,
+      })
+    }
+    if (document._type === 'book') {
+      await client.createOrReplace({
+        ...document,
+        _id: getDraftId(document._id),
+        author: undefined,
+      })
+    }
+  }
+
+  return {
+    label: 'Remove reference',
+    icon: TrashIcon,
+    tone: 'critical',
+    onHandle: handleRemoveReference,
+  }
+}

dev/test-studio/schema/author.ts

@@ -1,8 +1,9 @@
 import {UserIcon as icon} from '@sanity/icons'
 import {type StringRule} from '@sanity/types'
-import {defineField, defineType} from 'sanity'
+import {defineDecoration, defineField, defineType, isIncomingReferenceCreation} from 'sanity'
 
 import {AudienceSelectInput} from '../components/AudienceSelectInput'
+import {RemoveReferenceAction} from '../components/IncomingReferencesActions'
 
 // Generic decide field implementation that works for all types
 const defineLocalDecideField = (config: any) => {
@@ -103,6 +104,55 @@ export default defineType({
       },
       validation: (rule: StringRule) => rule.required(),
     }),
+    defineDecoration({
+      type: 'incomingReferences',
+      name: 'incomingReferencesDesigner',
+      title: 'Incoming references with the same role',
+      options: {
+        onLinkDocument: (document, reference) => {
+          return {
+            ...document,
+            bestFriend: reference,
+          }
+        },
+        filter: (context) => {
+          return {
+            filter: `role == $role`,
+            filterParams: {role: (context.document.role as string) || ''},
+          }
+        },
+        actions: [RemoveReferenceAction],
+        types: [{type: 'author'}],
+      },
+    }),
+    defineDecoration({
+      type: 'incomingReferences',
+      name: 'booksCreated',
+      title: 'Books created by this author',
+      options: {
+        onLinkDocument: (document, reference) => {
+          return {
+            ...document,
+            author: reference,
+          }
+        },
+        actions: [RemoveReferenceAction],
+        types: [
+          {type: 'book'},
+          {
+            type: 'book',
+            dataset: 'test-us',
+            title: 'Book in test-us dataset',
+            studioUrl: ({id, type}) => {
+              return type ? `/us/intent/edit/id=${id};type=${type}` : null
+            },
+            preview: {
+              select: {title: 'title', media: 'coverImage', subtitle: 'publicationYear'},
+            },
+          },
+        ],
+      },
+    }),
     {
       name: 'bestFriend',
       title: 'Best friend',
@@ -126,7 +176,6 @@ export default defineType({
       type: 'reference',
       to: [{type: 'author'}],
     }),
-
     {
       name: 'role',
       title: 'Role',
@@ -193,15 +242,32 @@ export default defineType({
     },
   ],
 
-  initialValue: () => ({
-    name: 'Foo',
-    bestFriend: {_type: 'reference', _ref: 'foo-bar'},
-    image: {
-      _type: 'image',
-      asset: {
-        _ref: 'image-8dcc1391e06e4b4acbdc6bbf2e8c8588d537cbb8-4896x3264-jpg',
-        _type: 'reference',
+  initialValue: (params) => {
+    if (isIncomingReferenceCreation(params)) {
+      return {
+        name: 'Foo',
+        bestFriend: params.reference,
+        image: {
+          _type: 'image',
+          asset: {
+            _ref: 'image-8dcc1391e06e4b4acbdc6bbf2e8c8588d537cbb8-4896x3264-jpg',
+            _type: 'reference',
+          },
+        },
+        role: params.from.fieldName === 'incomingReferencesDesigner' ? 'designer' : undefined,
+      }
+    }
+
+    return {
+      name: 'Foo',
+      bestFriend: {_type: 'reference', _ref: 'foo-bar'},
+      image: {
+        _type: 'image',
+        asset: {
+          _ref: 'image-8dcc1391e06e4b4acbdc6bbf2e8c8588d537cbb8-4896x3264-jpg',
+          _type: 'reference',
+        },
       },
-    },
-  }),
+    }
+  },
 })

dev/test-studio/schema/book.ts

@@ -1,5 +1,6 @@
 import {BookIcon} from '@sanity/icons'
-import {type Rule} from '@sanity/types'
+import {defineType, type Rule} from '@sanity/types'
+import {isIncomingReferenceCreation} from 'sanity'
 
 function formatSubtitle(book: any) {
   return [
@@ -12,7 +13,7 @@ function formatSubtitle(book: any) {
     .join(' ')
 }
 
-export default {
+export default defineType({
   name: 'book',
   type: 'document',
   title: 'Book',
@@ -154,7 +155,10 @@ export default {
       })
     },
   },
-  initialValue: {
-    title: 'Foo',
+  initialValue: (params) => {
+    return {
+      title: 'Foo',
+      author: isIncomingReferenceCreation(params) ? params.reference : undefined,
+    }
   },
-}
+})

dev/test-studio/schema/debug/decorationFields.tsx

@@ -0,0 +1,49 @@
+import {Box, Card, Text} from '@sanity/ui'
+import {defineDecoration, defineField, defineType} from 'sanity'
+
+export default defineType({
+  name: 'decorationFields',
+  type: 'document',
+  fields: [
+    defineDecoration({
+      name: 'noDefaultComponents',
+      type: 'formDecoration',
+      title: 'No default components',
+      description:
+        'This field has no default components, so it will use the default input component which shows a warning.',
+    }),
+    defineField({
+      name: 'withInput',
+      type: 'formDecoration',
+      title: 'With defined input',
+      description:
+        'This field has a defined input component, so it will use that one instead of the warning',
+      components: {
+        input: () => (
+          <Box paddingY={2}>
+            <Text size={1}>Using form decorator input component</Text>
+          </Box>
+        ),
+      },
+    }),
+    defineField({
+      name: 'withFieldAndInput',
+      type: 'formDecoration',
+      title: 'With defined field and input',
+      components: {
+        field: (props) => (
+          <Card padding={2} border tone="primary">
+            {props.renderDefault(props)}
+          </Card>
+        ),
+        input: () => (
+          <Card padding={2} border>
+            <Box padding={2}>
+              <Text size={1}>Using form decorator input component</Text>
+            </Box>
+          </Card>
+        ),
+      },
+    }),
+  ],
+})

dev/test-studio/schema/index.ts

@@ -18,6 +18,7 @@ import customInputsWithPatches from './debug/customInputsWithPatches'
 import customNumber from './debug/customNumber'
 import dateTimeValidation from './debug/dateTimeValidation'
 import dateValidation from './debug/dateValidation'
+import decorationFields from './debug/decorationFields'
 import {deprecatedDocument} from './debug/deprecatedDocument'
 import {
   deprecatedFields,
@@ -208,6 +209,7 @@ export function createSchemaTypes(projectId: string) {
     customNumber,
     dateTimeValidation,
     dateValidation,
+    decorationFields,
     deprecatedDocument,
     deprecatedFields,
     documentActions,

dev/test-studio/structure/constants.ts

@@ -49,6 +49,7 @@ export const DEBUG_INPUT_TYPES = [
   'customInputsTest',
   'customInputsWithPatches',
   'dateValidation',
+  'decorationFields',
   'dateTimeValidation',
   'deprecatedFields',
   'deprecatedDocument',

packages/@sanity/schema/src/_exports/_internal.ts

@@ -6,7 +6,7 @@ export {
   resolveSearchConfig,
   resolveSearchConfigForBaseFieldPaths,
 } from '../legacy/searchConfig/resolve'
-export {ALL_FIELDS_GROUP_NAME} from '../legacy/types/constants'
+export {ALL_FIELDS_GROUP_NAME, FORM_DECORATION} from '../legacy/types/constants'
 export {builtinTypes} from '../sanity/builtinTypes'
 export {createSchemaFromManifestTypes} from '../sanity/createSchemaFromManifestTypes'
 export {extractSchema} from '../sanity/extractSchema'

packages/@sanity/schema/src/descriptors/types.ts

@@ -79,7 +79,7 @@ export type ObjectMarker = {__type: 'object'; value: EncodableObject}
  */
 export interface CoreTypeDef extends CommonTypeDef {
   extends: null
-  jsonType: 'boolean' | 'number' | 'string' | 'object' | 'array'
+  jsonType: 'boolean' | 'number' | 'string' | 'object' | 'array' | 'null'
 }
 
 /**

packages/@sanity/schema/src/legacy/types/constants.ts

@@ -22,3 +22,11 @@ export const DEFAULT_OVERRIDEABLE_FIELDS = [
 export const OWN_PROPS_NAME = '_internal_ownProps'
 
 export const ALL_FIELDS_GROUP_NAME = 'all-fields'
+
+/**
+ * Name for configuring a decoration field type
+ * this fields are rendered in the form but are not extracted by the schema extractor.
+ * They serve only for UI purposes.
+ * @beta
+ */
+export const FORM_DECORATION = 'formDecoration'

packages/@sanity/schema/src/legacy/types/formDecoration.ts

@@ -0,0 +1,50 @@
+import {pick} from 'lodash'
+
+import primitivePreview from '../preview/primitivePreview'
+import {DEFAULT_OVERRIDEABLE_FIELDS, FORM_DECORATION, OWN_PROPS_NAME} from './constants'
+import {hiddenGetter} from './utils'
+
+const OVERRIDABLE_FIELDS = [...DEFAULT_OVERRIDEABLE_FIELDS]
+
+const FORM_DECORATION_CORE = {
+  name: FORM_DECORATION,
+  title: 'Form Decoration',
+  type: null,
+  jsonType: 'null',
+}
+
+export const formDecorationType = {
+  get() {
+    return FORM_DECORATION_CORE
+  },
+  extend(subTypeDef: any) {
+    const ownProps = {
+      ...subTypeDef,
+      preview: primitivePreview,
+    }
+
+    const parsed = Object.assign(pick(FORM_DECORATION_CORE, OVERRIDABLE_FIELDS), ownProps, {
+      type: FORM_DECORATION_CORE,
+    })
+
+    hiddenGetter(parsed, OWN_PROPS_NAME, ownProps)
+
+    return subtype(parsed)
+
+    function subtype(parent: any) {
+      return {
+        get() {
+          return parent
+        },
+        extend: (extensionDef: any) => {
+          const subOwnProps = pick(extensionDef, OVERRIDABLE_FIELDS)
+          const current = Object.assign({}, parent, subOwnProps, {
+            type: parent,
+          })
+          hiddenGetter(current, OWN_PROPS_NAME, subOwnProps)
+          return subtype(current)
+        },
+      }
+    }
+  },
+}

packages/@sanity/schema/src/legacy/types/index.ts

@@ -9,6 +9,7 @@ export {DateTimeType as datetime} from './datetime'
 export {DocumentType as document} from './document'
 export {EmailType as email} from './email'
 export {FileType as file} from './file'
+export {formDecorationType as formDecoration} from './formDecoration'
 export {GlobalDocumentReferenceType as globalDocumentReference} from './globalDocumentReference'
 export {ImageType as image} from './image'
 export {NumberType as number} from './number'

packages/@sanity/schema/src/sanity/builtinTypes/incomingReferences.ts

@@ -0,0 +1,5 @@
+export default {
+  name: 'incomingReferences',
+  title: 'Incoming references',
+  type: 'formDecoration',
+}

packages/@sanity/schema/src/sanity/builtinTypes/index.ts

@@ -8,6 +8,7 @@ import imageHotspot from './imageHotspot'
 import imageMetadata from './imageMetadata'
 import imagePalette from './imagePalette'
 import imagePaletteSwatch from './imagePaletteSwatch'
+import incomingReferences from './incomingReferences'
 import slug from './slug'
 
 export const builtinTypes = [
@@ -23,4 +24,5 @@ export const builtinTypes = [
   imageDimensions,
   imagePalette,
   imagePaletteSwatch,
+  incomingReferences,
 ]

packages/@sanity/schema/src/sanity/coreTypes.ts

@@ -1,3 +1,5 @@
+import {FORM_DECORATION} from '../legacy/types/constants'
+
 const coreTypes = [
   {name: 'array', jsonType: 'array', type: 'type'},
   {name: 'block', jsonType: 'object', type: 'type'},
@@ -20,6 +22,8 @@ const coreTypes = [
   {name: 'telephone', jsonType: 'string', type: 'type'},
   {name: 'text', jsonType: 'string', type: 'type'},
   {name: 'url', jsonType: 'string', type: 'type'},
+  {name: FORM_DECORATION, jsonType: 'null', type: 'type'},
+  {name: 'incomingReferences', jsonType: 'null', type: 'type'},
 ] as const
 
 export const coreTypeNames = coreTypes.map((t) => t.name)