feat: support link variants

src/Migration.ts

@@ -1,4 +1,5 @@
 import * as is from "./lib/isValue"
+import { getOptionalLinkProperties } from "./lib/getLinkProperties"
 import { validateAssetMetadata } from "./lib/validateAssetMetadata"
 
 import type { Asset } from "./types/api/asset/asset"
@@ -404,28 +405,32 @@ export class Migration<TDocuments extends PrismicDocument = PrismicDocument> {
 	 */
 	#migratePrismicDocumentData(input: unknown): unknown {
 		if (is.filledContentRelationship(input)) {
+			const optionalLinkProperties = getOptionalLinkProperties(input)
+
 			if (input.isBroken) {
 				return {
+					...optionalLinkProperties,
 					link_type: LinkType.Document,
 					// ID needs to be 16 characters long to be considered valid by the API
 					id: "_____broken_____",
 					isBroken: true,
-					text: input.text,
 				}
 			}
 
 			return {
+				...optionalLinkProperties,
 				link_type: LinkType.Document,
 				id: () => this._getByOriginalID(input.id),
-				text: input.text,
 			}
 		}
 
 		if (is.filledLinkToMedia(input)) {
+			const optionalLinkProperties = getOptionalLinkProperties(input)
+
 			return {
+				...optionalLinkProperties,
 				link_type: LinkType.Media,
 				id: this.createAsset(input),
-				text: input.text,
 			}
 		}
 

src/lib/getLinkProperties.ts

@@ -0,0 +1,25 @@
+import type { FilledContentRelationshipField } from "../types/value/contentRelationship"
+import type { OptionalLinkProperties } from "../types/value/link"
+import type { FilledLinkToMediaField } from "../types/value/linkToMedia"
+
+/**
+ * Returns optional properties only available to link fields. Link fields can
+ * have the same shape as content relationship and link to media fields,
+ * requiring special treatment to extract link-specific properties.
+ *
+ * @param input - The content relationship or link to media field from which the
+ *   link properties are extracted.
+ *
+ * @returns Optional link properties that `input` might have.
+ */
+export const getOptionalLinkProperties = (
+	input: FilledContentRelationshipField | FilledLinkToMediaField,
+): OptionalLinkProperties => {
+	const res: OptionalLinkProperties = {}
+
+	if ("text" in input) {
+		res.text = input.text
+	}
+
+	return res
+}

src/lib/resolveMigrationDocumentData.ts

@@ -38,7 +38,7 @@ export async function resolveMigrationContentRelationship(
 	if (relation instanceof PrismicMigrationDocument) {
 		return relation.document.id
 			? { link_type: LinkType.Document, id: relation.document.id }
-			: { link_type: LinkType.Document }
+			: { link_type: LinkType.Any }
 	}
 
 	if (relation) {
@@ -57,7 +57,7 @@ export async function resolveMigrationContentRelationship(
 		return { link_type: LinkType.Document, id: relation.id }
 	}
 
-	return { link_type: LinkType.Document }
+	return { link_type: LinkType.Any }
 }
 
 /**
@@ -167,7 +167,7 @@ export const resolveMigrationLinkToMedia = (
 		}
 	}
 
-	return { link_type: LinkType.Media }
+	return { link_type: LinkType.Any }
 }
 
 /**

src/types/migration/Asset.ts

@@ -1,6 +1,5 @@
 import type { Asset } from "../api/asset/asset"
 import type { FilledImageFieldImage } from "../value/image"
-import type { EmptyLinkField } from "../value/link"
 import type { LinkToMediaField } from "../value/linkToMedia"
 import { type RTImageNode } from "../value/richText"
 
@@ -89,7 +88,7 @@ export type MigrationLinkToMedia = Pick<
  */
 export type MigrationLinkToMediaField =
 	| Pick<LinkToMediaField<"filled">, "link_type" | "id" | "text">
-	| EmptyLinkField<"Media">
+	| LinkToMediaField<"empty">
 
 /**
  * A rich text image node in a migration.

src/types/migration/ContentRelationship.ts

@@ -1,6 +1,8 @@
-import type { FilledContentRelationshipField } from "../value/contentRelationship"
+import type {
+	ContentRelationshipField,
+	FilledContentRelationshipField,
+} from "../value/contentRelationship"
 import type { PrismicDocument } from "../value/document"
-import type { EmptyLinkField } from "../value/link"
 
 import type { PrismicMigrationDocument } from "./Document"
 
@@ -13,17 +15,16 @@ export type MigrationContentRelationship<
 	TDocuments extends PrismicDocument = PrismicDocument,
 > =
 	| ValueOrThunk<TDocuments | PrismicMigrationDocument<TDocuments> | undefined>
-	| (Pick<FilledContentRelationshipField, "link_type"> &
-			Partial<Pick<FilledContentRelationshipField, "text">> & {
-				id: ValueOrThunk<
-					TDocuments | PrismicMigrationDocument<TDocuments> | undefined
-				>
-			})
+	| (Pick<ContentRelationshipField, "link_type"> & {
+			id: ValueOrThunk<
+				TDocuments | PrismicMigrationDocument<TDocuments> | undefined
+			>
+	  })
 
 /**
  * The minimum amount of information needed to represent a content relationship
  * field with the migration API.
  */
 export type MigrationContentRelationshipField =
 	| Pick<FilledContentRelationshipField, "link_type" | "id">
-	| EmptyLinkField<"Document">
+	| ContentRelationshipField<string, string, unknown, "empty">

src/types/model/contentRelationship.ts

@@ -18,6 +18,5 @@ export interface CustomTypeModelContentRelationshipField<
 		select: typeof CustomTypeModelLinkSelectType.Document
 		customtypes?: readonly CustomTypeIDs[]
 		tags?: readonly Tags[]
-		allowText?: boolean
 	}
 }

src/types/model/link.ts

@@ -16,6 +16,7 @@ export interface CustomTypeModelLinkField {
 		allowText?: boolean
 		allowTargetBlank?: boolean
 		repeat?: boolean
+		variants?: string[]
 	}
 }
 

src/types/value/contentRelationship.ts

@@ -1,7 +1,6 @@
 import type { AnyRegularField, FieldState } from "./types"
 
 import type { GroupField } from "./group"
-import type { EmptyLinkField, LinkType } from "./link"
 import type { SliceZone } from "./sliceZone"
 
 /**
@@ -21,9 +20,13 @@ export type ContentRelationshipField<
 		| unknown = unknown,
 	State extends FieldState = FieldState,
 > = State extends "empty"
-	? EmptyLinkField<typeof LinkType.Document>
+	? EmptyContentRelationshipField
 	: FilledContentRelationshipField<TypeEnum, LangEnum, DataInterface>
 
+type EmptyContentRelationshipField = {
+	link_type: "Any"
+}
+
 /**
  * Links that refer to documents
  */
@@ -34,7 +37,7 @@ export interface FilledContentRelationshipField<
 		| Record<string, AnyRegularField | GroupField | SliceZone>
 		| unknown = unknown,
 > {
-	link_type: typeof LinkType.Document
+	link_type: "Document"
 	id: string
 	uid?: string
 	type: TypeEnum
@@ -44,5 +47,4 @@ export interface FilledContentRelationshipField<
 	slug?: string
 	isBroken?: boolean
 	data?: DataInterface
-	text?: string
 }

src/types/value/link.ts

@@ -1,8 +1,8 @@
 import type { AnyRegularField, FieldState } from "./types"
 
-import type { ContentRelationshipField } from "./contentRelationship"
+import type { FilledContentRelationshipField } from "./contentRelationship"
 import type { GroupField } from "./group"
-import type { LinkToMediaField } from "./linkToMedia"
+import type { FilledLinkToMediaField } from "./linkToMedia"
 import type { SliceZone } from "./sliceZone"
 
 /**
@@ -15,35 +15,13 @@ export const LinkType = {
 	Web: "Web",
 } as const
 
-/**
- * For link fields that haven't been filled
- *
- * @typeParam Type - The type of link.
- */
-export type EmptyLinkField<
-	Type extends (typeof LinkType)[keyof typeof LinkType] = typeof LinkType.Any,
-> = {
-	link_type: Type | string
-	text?: string
-}
-
-/**
- * Link that points to external website
- */
-export interface FilledLinkToWebField {
-	link_type: typeof LinkType.Web
-	url: string
-	target?: string
-	text?: string
-}
-
 /**
  * A link field.
  *
  * @typeParam TypeEnum - Type API ID of the document.
  * @typeParam LangEnum - Language API ID of the document.
- * @typeParam DataInterface - Data fields for the document (filled in via
- *   GraphQuery of `fetchLinks`).
+ * @typeParam DataInterface - Data fields for the document (filled via the
+ *   `fetchLinks` or `graphQuery` query parameter).
  * @typeParam State - State of the field which determines its shape.
  */
 export type LinkField<
@@ -53,9 +31,46 @@ export type LinkField<
 		| Record<string, AnyRegularField | GroupField | SliceZone>
 		| unknown = unknown,
 	State extends FieldState = FieldState,
-> = State extends "empty"
-	? EmptyLinkField<typeof LinkType.Any>
+> = (State extends "empty"
+	? EmptyLinkField
 	:
-			| ContentRelationshipField<TypeEnum, LangEnum, DataInterface, State>
-			| FilledLinkToWebField
-			| LinkToMediaField<State>
+			| FilledContentRelationshipField<TypeEnum, LangEnum, DataInterface>
+			| FilledLinkToMediaField
+			| FilledLinkToWebField) &
+	OptionalLinkProperties
+
+/**
+ * A link field that is not filled.
+ *
+ * @typeParam _Unused - THIS PARAMETER IS NOT USED. If you are passing a type,
+ *   **please remove it**.
+ */
+// This type needs `OptionalLinkProperties` because this type may be used on its own.
+export type EmptyLinkField<
+	_Unused extends
+		(typeof LinkType)[keyof typeof LinkType] = typeof LinkType.Any,
+> = {
+	link_type: "Any"
+} & OptionalLinkProperties
+
+/**
+ * A link field pointing to a relative or absolute URL.
+ */
+// This type needs `OptionalLinkProperties` because this type may be used on its own.
+export type FilledLinkToWebField = {
+	link_type: "Web"
+	url: string
+	target?: string
+} & OptionalLinkProperties
+
+/**
+ * Optional properties available to link fields. It is used to augment existing
+ * link-like fields (like content relationship fields) with field-specific
+ * properties.
+ *
+ * @internal
+ */
+export type OptionalLinkProperties = {
+	variant?: string
+	text?: string
+}

src/types/value/linkToMedia.ts

@@ -1,23 +1,24 @@
 import type { FieldState } from "./types"
 
-import type { EmptyLinkField, LinkType } from "./link"
-
 /**
  * A link field that points to media.
  *
  * @typeParam State - State of the field which determines its shape.
  */
 export type LinkToMediaField<State extends FieldState = FieldState> =
-	State extends "empty"
-		? EmptyLinkField<typeof LinkType.Media>
-		: FilledLinkToMediaField
+	State extends "empty" ? EmptyLinkToMediaField : FilledLinkToMediaField
+
+type EmptyLinkToMediaField = {
+	link_type: "Any"
+	text?: string
+}
 
 /**
  * A link that points to media.
  */
 export interface FilledLinkToMediaField {
 	id: string
-	link_type: typeof LinkType.Media
+	link_type: "Media"
 	name: string
 	kind: string
 	url: string

test/__snapshots__/writeClient-migrate-patch-contentRelationship.test.ts.snap

@@ -698,7 +698,7 @@ exports[`patches content relationship fields > lazyOtherCreateMissingID > group
   "group": [
     {
       "field": {
-        "link_type": "Document",
+        "link_type": "Any",
       },
     },
   ],
@@ -713,18 +713,18 @@ exports[`patches content relationship fields > lazyOtherCreateMissingID > shared
       "items": [
         {
           "field": {
-            "link_type": "Document",
+            "link_type": "Any",
           },
         },
       ],
       "primary": {
         "field": {
-          "link_type": "Document",
+          "link_type": "Any",
         },
         "group": [
           {
             "field": {
-              "link_type": "Document",
+              "link_type": "Any",
             },
           },
         ],
@@ -746,13 +746,13 @@ exports[`patches content relationship fields > lazyOtherCreateMissingID > slice
       "items": [
         {
           "field": {
-            "link_type": "Document",
+            "link_type": "Any",
           },
         },
       ],
       "primary": {
         "field": {
-          "link_type": "Document",
+          "link_type": "Any",
         },
       },
       "slice_label": "Vel",
@@ -765,7 +765,7 @@ exports[`patches content relationship fields > lazyOtherCreateMissingID > slice
 exports[`patches content relationship fields > lazyOtherCreateMissingID > static zone 1`] = `
 {
   "field": {
-    "link_type": "Document",
+    "link_type": "Any",
   },
 }
 `;