feat!: v5

.github/workflows/ci.yml

@@ -79,7 +79,7 @@ jobs:
         os: [ubuntu-latest]
         node: [22]
         # Add relevant versions from: https://majors.nullvoxpopuli.com/q?minors=on&packages=typescript
-        typescript: ["4.9", "5.0", "5.1", "5.2", "5.3", "5.4"]
+        typescript: ["5.3", "5.4", "5.5", "5.6"]
 
 
     steps:

README.md

@@ -52,7 +52,7 @@ For more clarity on this project and its structure you can also check out the de
 ## License
 
 ```
-   Copyright 2013-2023 Prismic <contact@prismic.io> (https://prismic.io)
+   Copyright 2013-2024 Prismic <contact@prismic.io> (https://prismic.io)
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

eslint.config.mjs

@@ -11,9 +11,9 @@ export default tseslint.config(
 	},
 	eslint.configs.recommended,
 	tseslint.configs.recommended,
-	prettier,
 	...pluginVue.configs["flat/essential"],
 	...vueTsEslintConfig(),
+	prettier,
 	{
 		plugins: {
 			tsdoc,
@@ -44,6 +44,7 @@ export default tseslint.config(
 			"@typescript-eslint/consistent-type-imports": "error",
 			"tsdoc/syntax": "warn",
 			"vue/multi-word-component-names": "off",
+			"vue/no-v-text-v-html-on-component": "off",
 		},
 	},
 )

messages/alt-must-be-an-empty-string.md

@@ -0,0 +1,28 @@
+# `alt` must be an empty string
+
+`<PrismicImage>` allows the `alt` HTML attribute to be configured using two props: `alt` and `fallbackAlt`.
+
+Both `alt` and `fallbackAlt` can only be used to [declare an image as decorative][mdn-alt-decorative-image] by pasing an empty string. You may not pass arbitrary alternative text to the `alt` prop.
+
+```html
+<!-- Will render `alt` using the Image field's `alt` property. -->
+<PrismicImage :field="doc.data.imageField" />
+
+<!-- Will always render `alt=""`. -->
+<PrismicImage :field="doc.data.imageField" alt="" />
+
+<!-- Will render `alt=""` only if the Image field's alt property is empty. -->
+<PrismicImage :field="doc.data.imageField" fallbackAlt="" />
+```
+
+All images should have an alt value. `<PrismicImage>` will automatically use the Image field's `alt` property written in the Prismic Editor. If the Image field's `alt` property is empty, the `alt` HTML attribute will not be included _unless_ one of `alt` or `fallbackAlt` is used.
+
+For more details on decorative images, [see the MDN article on the `<img>` HTML element's `alt` attribute][mdn-alt-decorative-image].
+
+## Deciding between `alt=""` and `fallbackAlt=""`
+
+`alt=""` will always mark the image as decorative, ignoring the provied Image field's `alt` property. Use this when the image is always used for decorative or presentational purposes.
+
+`fallbackAlt=""` will only mark the image as decorative if the provided Image field's `alt` property is empty. Use this when you want to mark the image as decorative _unless_ alternative text is provided in the Prismic Editor. **Generally speaking, this is discouraged**; prefer marking the image as decorative intentionally.
+
+[mdn-alt-decorative-image]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/alt#decorative_images

messages/html-serialization-is-deprecated-with-prismic-rich-text.md

@@ -0,0 +1,51 @@
+# HTML serialization is deprecated with `<PrismicRichText>`
+
+As of [`@prismicio/vue`][prismic-vue] v5, `<PrismicRichText>` introduces a new components-based serializer, replacing the previous HTML-based serialization method. This change improves flexibility and security by eliminating the need for the `v-html` directive.
+
+The HTML-based serializer is still accessible to ease your upgrade path to `@prismicio/vue` v5 but **will be removed in a future major version**. We encourage you to migrate to the new components-based serializer to ensure future compatibility.
+
+## Migration example
+
+Here’s how to transition from the old HTML-based serializer to the new components-based serializer:
+
+### Deprecated method (HTML-based Serializer)
+
+```html
+<PrismicRichText
+	:field="doc.data.imageField"
+	:serializer="{
+		heading1: ({ children }) => `<h2>${children}</h2>`
+	}"
+/>
+```
+
+### New method (Components-based Serializer)
+
+```html
+<PrismicRichText
+	:field="doc.data.imageField"
+	:serializer="{
+		// Use a `Heading2` component to render `heading1` rich text nodes
+		heading1: Heading2
+	}"
+/>
+```
+
+The above snippet relies on an `Heading2.vue` component. Here's an example of this component:
+
+```html
+<script setup>
+import { getSliceComponentProps } from "@prismicio/vue"
+
+defineProps(getRichTextComponentProps())
+</script>
+
+<template>
+	<h2>{{ node.children }}</h2>
+</template>
+```
+
+Learn more about the new component serializer on [`@prismicio/vue` technical references][prismic-vue-rich-text].
+
+[prismic-vue]: https://prismic.io/docs/technical-reference/prismicio-vue
+[prismic-vue-rich-text]: https://prismic.io/docs/technical-reference/prismicio-vue#prismicrichtext

messages/missing-link-properties.md

@@ -0,0 +1,65 @@
+# Missing Link properties
+
+`<PrismicLink>` requires specific properties in the provided field or document to render properly. This requirement extends to [Link][link-fields], [Link to Media][link-fields], and [Content Relationship][link-fields] fields.
+
+If the required properties are missing, `<PrismicLink>` will not render the link.
+
+**Note**: When using Prismic's [Rest API][rest-api] (the default when using `@prismicio/client`), the required fields are automatically included. When using Prismic's [GraphQL API][graphql-api], you must include these fields in your query.
+
+## Required Properties
+
+### With the `field` prop
+
+The following properties are requried when using the `field` prop with a Link, Link to Media, or Content Relationship field:
+
+- `link_type` (or `_linkType` when using Prismic's [GraphQL API][graphql-api])
+- `id`
+- `url`
+- `uid` (only if your website uses a [Link Resolver][link-resolver] that uses a document's UID field)
+
+The following properties are not required, but are recommended:
+
+- `target`
+
+**Example**:
+
+```html
+<PrismicLink :field="doc.data.linkField">Click me</PrismicLink>
+```
+
+### With the `document` prop
+
+The following properties are requried when using the `document` prop with a Prismic document:
+
+- `id`
+- `url`
+- `uid` (only if your website uses a [Link Resolver][link-resolver] that uses a document's UID field)
+
+**Example**:
+
+```html
+<PrismicLink :document="doc">Click me</PrismicLink>
+```
+
+## GraphQL Example
+
+When using Prismic's [GraphQL API][graphql-api], Link fields must be queried with at least the following properties:
+
+```diff
+  {
+  	page(uid: "home", lang: "en-us") {
+  		linkField {
++ 			_linkType
++ 			id
++ 			url
++ 			uid # only required if your website uses a Link Resolver that uses a document's UID field.
++ 			target # not required, but recommended for automatic `target` handling
+  		}
+  	}
+  }
+```
+
+[link-fields]: https://prismic.io/docs/content-relationship
+[link-resolver]: https://prismic.io/docs/route-resolver#link-resolver
+[rest-api]: https://prismic.io/docs/rest-api-technical-reference
+[graphql-api]: https://prismic.io/docs/graphql-technical-reference

messages/prismictext-works-only-with-rich-text-and-title-fields.md

@@ -0,0 +1,24 @@
+# `<PrismicText>` works only with Rich Text and Title fields
+
+`<PrismicText>` works only with [Rich Text and Title fields][rich-text-title-field]. It renders the field's value as plain text (i.e. with no formatting, paragraphs, or headings).
+
+```html
+<!-- Will render a plain text version of the Rich Text field's value. -->
+<PrismicText :field="doc.data.richTextField" />
+```
+
+Other text-based field types, such as [Key Text][key-text-field] and [Select][select-field], cannot be rendered using `<PrismicText>`.
+
+Since Key Text and Select field values are already plain text, you can render them inline without a special component.
+
+```html
+<!-- Will render the Key Text field's value. -->
+<span>{doc.data.keyTextField}</span>
+
+<!-- Will render the Select field's value. -->
+<span>{doc.data.selectField}</span>
+```
+
+[rich-text-title-field]: https://prismic.io/docs/rich-text
+[key-text-field]: https://prismic.io/docs/field#key-text
+[select-field]: https://prismic.io/docs/field#select