refactor: link types

[angeloashmore]

Resolves: https://prismic-team.slack.com/archives/C02L3FN3AJK/p1734036664049009?thread_ts=1734004341.679669&cid=C02L3FN3AJK

Description

This PR refactors how we handle link fields values.

Prismic is beginning to separate the link field type from the content relationship and link to media field types. Link fields can now be configured to include optional properties, like text and variant. We don't want these link-specific fields to appear in content relationship and link to media fields.

Before this PR, the LinkField and EmptyLinkField types were tightly coupled with the content relationship and link to media fields. The coupling made it difficult to add optional properties only to link fields.

In this PR, we decouple the fields so we can more easily add new properties. Link fields have the same shape as content relationship and link to media fields when a document or media item is linked, so there is still some connection.

Notable changes

• EmptyLinkField, an exported type, has been corrected to always use { "link_type": "Any" }. Before this PR, the field could incorrectly be configured to use "Document", "Media", or "Web". It's possible those were valid values before the Page Builder.
• The migration API now correctly includes optional link properties only on link fields, not content relationship or link to media fields.

How to add additional optional link properties

This refactoring should make it easier to add or modify optional link properties. These properties are scoped to link fields only and will not appear on content relationship or link to media fields.

1. Add the optional property to the OptionalLinkProperties type.
2. Conditionally add the optional property in src/lib/getOptionalLinkProperties.ts.
3. Update tests.

See #368 for an example.

Checklist

• A comprehensive Linear ticket, providing sufficient context and details to facilitate the review of the PR, is linked to the PR.
• If my changes require tests, I added them.
• If my changes affect backward compatibility, it has been discussed.
• If my changes require an update to the CONTRIBUTING.md guide, I updated it.

Preview

How to QA ¹

Footnotes

1. Please use these labels when submitting a review:
   ❓ #ask: Ask a question.
   💡 #idea: Suggest an idea.
   ⚠️ #issue: Strongly suggest a change.
   🎉 #nice: Share a compliment. ↩

[xrutayisire]

❓ Why did you remove text here? It's used in resolveMigrationContentRelationship and from what I understood with Lucie will still be used while handling link to document that can be from a generic link.

[angeloashmore]

text was removed because this type defines how users specify a content relationship value. text is invalid for content relationship fields.

Internally, we needed to widen the types after verifying the shape, not before. You can see the & OptionalLinkProperties in src/lib/isValue.ts and src/lib/isMigrationValue.ts.

These changes support the following behavior when migrating a document:

• Content relationship fields will not include text or variant.
• Link to media fields will not include variant. It includes text only because we explicitly added it to the field type. We can easily remove it for this field type only if we decide to do so.
• Link fields include text and variant.

[xrutayisire]

Hum, I'm not sure to get everything.

Content relationship fields will not include text or variant.

That I understand, but what's the difference with link to document? What I understood from Lucie is that the type is used also for migrating link to document implying that text and variant are supported.
There is no difference between link to document and content relationship behind the scene. Right?

Link to media fields will not include variant. It includes text only because we explicitly added it to the field type. We can easily remove it for this field type only if we decide to do so.

For me, it's either both text + variant or nothing. We are waiting for the product but meanwhile, I would go for both. (details we can take care of course)

[angeloashmore]

That I understand, but what's the difference with link to document? What I understood from Lucie is that the type is used also for migrating link to document implying that text and variant are supported.
There is no difference between link to document and content relationship behind the scene. Right?

Content relationship functions are used for both content relationship fields and link fields. From the public API, we want to separate these field types so they only accept what is allowed. From the internal API, we need to treat both field types as overlapping.

Before this PR, we made the overlap public, which meant devs could assign text to a content relationship field, which should not be allowed.

Here is what the autocomplete looks like after this PR for each field type:

Link type	Autocomplete	Notes
Link field		Includes text and variant, along with the other migration-specific properties.
Link to media		Includes text.
Content relationship		Does not include text or variants.

For me, it's either both text + variant or nothing. We are waiting for the product but meanwhile, I would go for both. (details we can take care of course)

I'm happy to remove text from link to media if we want to do that. I left it in since that's how the product works today. Are you good with removing it from @prismicio/client now?