feat(core): Global Document References support

dev/test-studio/sanity.config.ts

@@ -267,6 +267,18 @@ export default defineConfig([
       enabled: true,
     },
   },
+  {
+    name: 'playground-staging',
+    title: 'playground (Staging)',
+    projectId: 'exx11uqh',
+    dataset: 'playground',
+    plugins: [sharedSettings()],
+    basePath: '/playground-staging',
+    apiHost: 'https://api.sanity.work',
+    auth: {
+      loginMethod: 'token',
+    },
+  },
   {
     name: 'custom-components',
     title: 'Test Studio',

dev/test-studio/schema/index.ts

@@ -96,6 +96,9 @@ import date from './standard/date'
 import datetime from './standard/datetime'
 import emails from './standard/emails'
 import files from './standard/files'
+import globalDocumentReference, {
+  globalDocumentReferenceSubtype,
+} from './standard/globalDocumentReference'
 import images, {myImage} from './standard/images'
 import numbers from './standard/numbers'
 import objects, {myObject} from './standard/objects'
@@ -289,6 +292,8 @@ export const schemaTypes = [
   conditionalFieldset,
   crossDatasetReference,
   crossDatasetSubtype,
+  globalDocumentReference,
+  globalDocumentReferenceSubtype,
   fieldGroupsWithFieldsets,
   ptReference,
   validationTest,

dev/test-studio/schema/standard/globalDocumentReference.ts

@@ -0,0 +1,206 @@
+import {BookIcon, MoonIcon, UserIcon} from '@sanity/icons'
+import {defineType} from 'sanity'
+
+export const globalDocumentReferenceSubtype = defineType({
+  type: 'globalDocumentReference',
+  name: 'globalDocumentSubtype',
+  title: 'Subtype of global document references',
+  resourceType: 'dataset',
+  resourceId: 'exx11uqh.blog',
+  to: [
+    {
+      type: 'book',
+      icon: BookIcon,
+      preview: {
+        select: {
+          title: 'title',
+          media: 'coverImage',
+        },
+        prepare(val) {
+          return {
+            title: val.title,
+            media: val.coverImage,
+          }
+        },
+      },
+    },
+  ],
+})
+
+export default defineType({
+  name: 'globalDocumentReferenceTest',
+  type: 'document',
+  title: 'Global document reference test',
+  description: 'Test cases for global document references',
+  icon: MoonIcon,
+  fields: [
+    {name: 'title', type: 'string'},
+    {
+      name: 'bookInPlayground',
+      title: 'Reference to book in the "playground" dataset',
+      type: 'globalDocumentReference',
+      resourceType: 'dataset',
+      resourceId: 'exx11uqh.blog',
+      studioUrl: ({id, type}) => {
+        return type
+          ? `${document.location.protocol}//${document.location.host}/playground/content/${type};${id}`
+          : null
+      },
+      to: [
+        {
+          type: 'book',
+          icon: BookIcon,
+          preview: {
+            select: {
+              title: 'title',
+              subtitle: 'descriptionMd',
+              media: 'coverImage',
+            },
+            prepare(val) {
+              return {
+                title: val.title,
+                subtitle: val.subtitle,
+                media: val.coverImage,
+              }
+            },
+          },
+        },
+      ],
+    },
+    {
+      title: 'Reference to book or author in the "playground" dataset',
+      name: 'bookOrAuthorInPlayground',
+      type: 'globalDocumentReference',
+      resourceType: 'dataset',
+      resourceId: 'exx11uqh.blog',
+      weak: true,
+      studioUrl: ({id, type}) => {
+        return type
+          ? `${document.location.protocol}//${document.location.host}/playground/content/${type};${id}`
+          : null
+      },
+      to: [
+        {
+          type: 'book',
+          icon: BookIcon,
+          preview: {
+            select: {
+              title: 'title',
+              subtitle: 'descriptionMd',
+              coverImage: 'coverImage',
+            },
+            prepare(val) {
+              return {
+                title: val.title,
+                subtitle: val.subtitle,
+                media: val.coverImage,
+              }
+            },
+          },
+        },
+        {
+          type: 'author',
+          icon: UserIcon,
+          preview: {
+            select: {
+              title: 'name',
+            },
+            prepare(val) {
+              return {
+                title: val.title,
+                media: val.media,
+              }
+            },
+          },
+        },
+      ],
+    },
+    {
+      title: 'GDR in PTE',
+      name: 'portableText',
+      type: 'array',
+      of: [
+        {type: 'block'},
+        {
+          title: 'GDR subtype test',
+          name: 'globalDocumentSubtype',
+          type: 'globalDocumentSubtype',
+        },
+      ],
+    },
+    {
+      title: 'GDR in array',
+      name: 'array',
+      type: 'array',
+      of: [
+        {
+          title: 'GDR subtype test',
+          name: 'globalDocumentSubtype',
+          type: 'globalDocumentSubtype',
+        },
+      ],
+    },
+    {
+      title: 'GDR subtype test',
+      name: 'globalDocumentSubtype',
+      type: 'globalDocumentSubtype',
+    },
+    {
+      name: 'initialValueTest',
+      type: 'globalDocumentReference',
+      resourceType: 'dataset',
+      resourceId: 'exx11uqh.blog',
+      studioUrl: ({id, type}) => {
+        return type
+          ? `${document.location.protocol}//${document.location.host}/playground/content/${type};${id}`
+          : null
+      },
+      to: [
+        {
+          type: 'book',
+          icon: BookIcon,
+          preview: {
+            select: {
+              title: 'title',
+              subtitle: 'descriptionMd',
+              media: 'coverImage',
+            },
+            prepare(val) {
+              return {
+                title: val.title,
+                subtitle: val.subtitle,
+                media: val.coverImage,
+              }
+            },
+          },
+        },
+      ],
+      initialValue: () => ({
+        _type: 'reference',
+        _ref: 'dataset:exx11uqh.blog:4203c6bd-98c2-418e-9558-3ed56ebaf1d8',
+        _weak: true,
+      }),
+    },
+  ],
+  preview: {
+    select: {
+      title: 'title',
+      authorRefName: 'bookOrAuthorInPlayground.name',
+      authorBff: 'bookOrAuthorInPlayground.bestFriend.name',
+      bookRefTitle: 'bookOrAuthorInPlayground.title',
+    },
+    prepare(values) {
+      return {
+        title: values.title,
+        subtitle: [
+          values.authorRefName
+            ? `Author: ${values.authorRefName} (${`Bff: ${values.authorBff || 'none'}`})`
+            : '',
+          values.bookRefTitle ? `Book title: ${values.bookRefTitle}` : '',
+        ]
+          .filter(Boolean)
+          .join(', '),
+      }
+    },
+  },
+})

dev/test-studio/structure/constants.ts

@@ -13,6 +13,7 @@ export const STANDARD_INPUT_TYPES = [
   'stringsTest',
   'textsTest',
   'urlsTest',
+  'globalDocumentReferenceTest',
 ]
 
 export const STANDARD_PORTABLE_TEXT_INPUT_TYPES = [

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

@@ -0,0 +1,107 @@
+import arrify from 'arrify'
+import {pick} from 'lodash'
+
+import {DEFAULT_OVERRIDEABLE_FIELDS} from './constants'
+import {lazyGetter} from './utils'
+
+export const REF_FIELD = {
+  name: '_ref',
+  title: 'Referenced document ID',
+  type: 'string',
+}
+
+export const WEAK_FIELD = {
+  name: '_weak',
+  title: 'Weak reference',
+  type: 'boolean',
+}
+
+const REFERENCE_FIELDS = [REF_FIELD, WEAK_FIELD]
+
+const OVERRIDABLE_FIELDS = [...DEFAULT_OVERRIDEABLE_FIELDS]
+
+const GLOBAL_DOCUMENT_REFERENCE_CORE = {
+  name: 'globalDocumentReference',
+  title: 'Global Document Reference',
+  type: null,
+  jsonType: 'object',
+}
+
+function humanize(arr: any, conjunction: any) {
+  const len = arr.length
+  if (len === 1) {
+    return arr[0]
+  }
+  const first = arr.slice(0, len - 1)
+  const last = arr[len - 1]
+  return `${first.join(', ')} ${conjunction} ${last}`
+}
+
+function buildTitle(type: any) {
+  if (!type.to || type.to.length === 0) {
+    return 'Global Document Reference'
+  }
+  return `Global Document Reference to ${humanize(
+    arrify(type.to).map((toType: any) => toType.title),
+    'or',
+  ).toLowerCase()}`
+}
+
+export const GlobalDocumentReferenceType = {
+  get() {
+    return GLOBAL_DOCUMENT_REFERENCE_CORE
+  },
+  extend(subTypeDef: any, createMemberType: any) {
+    if (!subTypeDef.to) {
+      throw new Error(
+        `Missing "to" field in global document reference definition. Check the type ${subTypeDef.name}`,
+      )
+    }
+    const parsed = Object.assign(
+      pick(GLOBAL_DOCUMENT_REFERENCE_CORE, OVERRIDABLE_FIELDS),
+      subTypeDef,
+      {
+        type: GLOBAL_DOCUMENT_REFERENCE_CORE,
+      },
+    )
+
+    lazyGetter(parsed, 'fields', () => {
+      return REFERENCE_FIELDS.map((fieldDef) => {
+        const {name, ...type} = fieldDef
+        return {
+          name: name,
+          type: createMemberType(type),
+        }
+      })
+    })
+
+    lazyGetter(parsed, 'to', () => {
+      return arrify(subTypeDef.to).map((toType: any) => {
+        return {
+          ...toType,
+        }
+      })
+    })
+
+    lazyGetter(parsed, 'title', () => subTypeDef.title || buildTitle(parsed))
+
+    return subtype(parsed)
+
+    function subtype(parent: any) {
+      return {
+        get() {
+          return parent
+        },
+        extend: (extensionDef: any) => {
+          if (extensionDef.of) {
+            throw new Error('Cannot override `of` of subtypes of "globalDocumentReference"')
+          }
+          const current = Object.assign({}, parent, pick(extensionDef, OVERRIDABLE_FIELDS), {
+            type: parent,
+          })
+          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 {GlobalDocumentReferenceType as globalDocumentReference} from './globalDocumentReference'
 export {ImageType as image} from './image'
 export {NumberType as number} from './number'
 export {ObjectType as object} from './object'

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

@@ -13,6 +13,7 @@ const coreTypes = [
   {name: 'object', jsonType: 'object', type: 'type'},
   {name: 'reference', jsonType: 'object', type: 'type'},
   {name: 'crossDatasetReference', jsonType: 'object', type: 'type'},
+  {name: 'globalDocumentReference', jsonType: 'object', type: 'type'},
   {name: 'slug', jsonType: 'object', type: 'type'},
   {name: 'span', jsonType: 'object', type: 'type'},
   {name: 'string', jsonType: 'string', type: 'type'},

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

@@ -180,6 +180,11 @@ export function extractSchema(
       return {type: 'unknown'} satisfies UnknownTypeNode // we don't support cross-dataset references at the moment
     }
 
+    // Global document references are not supported
+    if (isGlobalDocumentReferenceType(schemaType)) {
+      return {type: 'unknown'} satisfies UnknownTypeNode // we don't support global document references at the moment
+    }
+
     if (isReferenceType(schemaType)) {
       return createReferenceTypeNodeDefintion(schemaType)
     }
@@ -404,6 +409,9 @@ function isReferenceType(typeDef: SanitySchemaType): typeDef is ReferenceSchemaT
 function isCrossDatasetReferenceType(typeDef: SanitySchemaType) {
   return isType(typeDef, 'crossDatasetReference')
 }
+function isGlobalDocumentReferenceType(typeDef: SanitySchemaType) {
+  return isType(typeDef, 'globalDocumentReference')
+}
 function isStringType(typeDef: SanitySchemaType): typeDef is StringSchemaType {
   return isType(typeDef, 'string')
 }