Provide feedback when a <PrismicLink> component receives an invalid value

[angeloashmore]

Is your feature request related to a problem? Please describe.

<PrismicLink> accepts a Prismic Link field and renders an appropriate link element. If the Link field is empty or is null, <PrismicLink> renders null.

<PrismicLink>'s empty field handling can be difficult to debug when an invalid value is provided. It currently "fails" silently since the component treats an empty or nonexistant value is "empty." An invalid value may be provided if Route Resolver or Link Resolver is not set up properly, or the wrong type of data is provided.

Describe the solution you'd like

<PrismicLink> could implement one or more of the following techniques:

Warn when a filled Link field is provided without a Link Resolver or url property.

A Link field can be one of the following types:

type Link =
  | null
  | {
      type: "Any";
    }
  | {
      type: "Document";
      // document-specific properties
    }
  | {
      type: "Media";
      // media-specific properties
    }
  | {
      type: "Web";
      // web-specific properties
    };

If the field contains type: Document but does not have a url property, we know Route Resolver was not configured. If the url property is missing and we don't have a Link Resolver, we also know Link Resolver was not configured.

In that case, we can print a warning to the console with instructions on how to solve the issue and possible causes.

Describe alternatives you've considered

Provide a fallback prop

If a field is empty, we can render a fallback value. This is equivalent to using @prismicio/helper's isFilled.link() helper directly, but through a React API.

Using the fallback prop would help developers know that the field was treated as empty, helping them better understand the data that was passed in.

<PrismicLink
  field={page.data.myLinkField}
  fallback={<span className="text-red">A link was not provided</span>}
>
  Click me!
</PrismicLink>

This prop may be useful on its own, outside of this feature request.

Provide an optional prop

If a field is empty, we can throw an error or print a warning to the console. This helps developers immediately know an invalid value was provided. If the component is marked as optional, no error will be thrown or logged. null would be rendered.

<PrismicLink
  field={page.data.myLinkField}
  optional={true}
>
  Click me!
</PrismicLink>

The fallback prop may be a better API than a single-use optional prop. The above described behavior could be accomplished with fallback={null}, which is more explicit.

Additional context

The debugging trouble explained in the intro has been experienced by several developers. It usually comes from misconfiguring @prismicio/client or @prismicio/react. Although it is technically "user error", we can help developers fix the issue by providing a helpful message.

If long-form messaging is helpful, we can add a message to the GitHub repository and link to it via prismic.dev.

---

Reported by @Duaner

[lihbr]

LGTM, just a note to put the incentive on the Route Resolver inside the warning message.

Wondering how we could standardize those kinds of behavior/checks across SDKs 🤔 i.e. Should this be part of asLink() for example/instead?