@prismicio/vue 4.3.0 → 5.0.0-alpha.0

package/src/PrismicLink.vue

@@ -0,0 +1,191 @@
+<script lang="ts" setup>
+import type { AsLinkAttrsConfig } from "@prismicio/client"
+import {
+	type LinkField,
+	type LinkResolverFunction,
+	type PrismicDocument,
+	asLinkAttrs,
+} from "@prismicio/client"
+import { DEV } from "esm-env"
+import { computed, watchEffect } from "vue"
+
+import { devMsg } from "./lib/devMsg"
+import { isInternalURL } from "./lib/isInternalURL"
+
+import type { ComponentOrTagName } from "./types"
+
+import { usePrismic } from "./usePrismic"
+
+/**
+ * The default component rendered for internal URLs.
+ */
+const defaultInternalComponent = "router-link"
+
+/**
+ * The default component rendered for external URLs.
+ */
+const defaultExternalComponent = "a"
+
+/**
+ * The default rel attribute rendered for external URLs.
+ */
+const defaultExternalRelAttribute = "noreferrer"
+
+/**
+ * Props for `<PrismicLink />`.
+ */
+export type PrismicLinkProps = {
+	/**
+	 * A link resolver function used to resolve links when not using the route
+	 * resolver parameter with `@prismicio/client`.
+	 *
+	 * @defaultValue The link resolver provided to `@prismicio/vue` plugin if configured.
+	 *
+	 * @see Link resolver documentation {@link https://prismic.io/docs/core-concepts/link-resolver-route-resolver#link-resolver}
+	 */
+	linkResolver?: LinkResolverFunction
+
+	/**
+	 * The `rel` attribute for the link. By default, `"noreferrer"` is provided if
+	 * the link's URL is external. This prop can be provided a function to use the
+	 * link's metadata to determine the `rel` value.
+	 *
+	 * @defaultValue The one provided to `@prismicio/vue` plugin if configured.
+	 */
+	rel?: string | AsLinkAttrsConfig["rel"]
+
+	/**
+	 * An HTML tag name or a component used to render internal links.
+	 *
+	 * @remarks
+	 * HTML tag names will be rendered using the anchor tag interface (`href`,
+	 * `target`, and `rel` attributes).
+	 * @remarks
+	 * Components will be rendered using Vue Router {@link RouterLink} interface
+	 * (`to` props).
+	 *
+	 * @defaultValue The one provided to `@prismicio/vue` plugin if configured, {@link RouterLink} otherwise.
+	 */
+	internalComponent?: ComponentOrTagName
+
+	/**
+	 * An HTML tag name or a component used to render external links.
+	 *
+	 * @remarks
+	 * HTML tag names will be rendered using the anchor tag interface (`href`,
+	 * `target`, and `rel` attributes).
+	 * @remarks
+	 * Components will be rendered using Vue Router {@link RouterLink} interface
+	 * (`to` props).
+	 *
+	 * @defaultValue The one provided to `@prismicio/vue` plugin if configured, `"a"` otherwise.
+	 */
+	externalComponent?: ComponentOrTagName
+} & (
+	| {
+			/**
+			 * The Prismic link field to render.
+			 */
+			field: LinkField
+			document?: never
+	  }
+	| {
+			/**
+			 * The Prismic document to render as a link.
+			 */
+			document: PrismicDocument
+			field?: never
+	  }
+)
+
+const props = defineProps<PrismicLinkProps>()
+defineOptions({ name: "PrismicLink" })
+
+const { options } = usePrismic()
+
+if (DEV) {
+	watchEffect(() => {
+		if (props.field) {
+			if (!props.field.link_type) {
+				console.error(
+					`[PrismicLink] This "field" prop value caused an error to be thrown.\n`,
+					props.field,
+				)
+				throw new Error(
+					`[PrismicLink] The provided field is missing required properties to properly render a link. The link will not render. For more details, see ${devMsg(
+						"missing-link-properties",
+					)}`,
+				)
+			} else if (
+				("text" in props.field
+					? Object.keys(props.field).length > 2
+					: Object.keys(props.field).length > 1) &&
+				!("url" in props.field || "uid" in props.field || "id" in props.field)
+			) {
+				console.warn(
+					`[PrismicLink] The provided field is missing required properties to properly render a link. The link may not render correctly. For more details, see ${devMsg(
+						"missing-link-properties",
+					)}`,
+					props.field,
+				)
+			}
+		} else if (props.document) {
+			if (!("url" in props.document || "id" in props.document)) {
+				console.warn(
+					`[PrismicLink] The provided document is missing required properties to properly render a link. The link may not render correctly. For more details, see ${devMsg(
+						"missing-link-properties",
+					)}`,
+					props.document,
+				)
+			}
+		}
+	})
+}
+
+const rawAttrs = computed(() => {
+	return asLinkAttrs(props.field || props.document, {
+		linkResolver: props.linkResolver || options.linkResolver,
+		rel(args) {
+			const maybeRel = props.rel || options.components?.linkRel
+			if (maybeRel) {
+				return typeof maybeRel === "function" ? maybeRel(args) : maybeRel
+			}
+
+			return args.isExternal ? defaultExternalRelAttribute : undefined
+		},
+	})
+})
+
+const component = computed(() => {
+	return isInternalURL(rawAttrs.value.href || "")
+		? props.internalComponent ||
+				options.components?.linkInternalComponent ||
+				defaultInternalComponent
+		: props.externalComponent ||
+				options.components?.linkExternalComponent ||
+				defaultExternalComponent
+})
+
+// Match Vue Router's `<RouterLink />` interface unless the component is an anchor tag.
+const attrs = computed(() => {
+	return component.value === "a"
+		? {
+				href: rawAttrs.value.href,
+				target: rawAttrs.value.target,
+				rel: rawAttrs.value.rel,
+			}
+		: {
+				to: rawAttrs.value.href,
+				target: rawAttrs.value.target,
+				rel: rawAttrs.value.rel,
+			}
+})
+</script>
+
+<template>
+	<component :is="component" v-bind="attrs">
+		<slot>
+			{{ props.field && "text" in props.field ? props.field.text : undefined }}
+		</slot>
+	</component>
+</template>

package/src/PrismicRichText/DeprecatedPrismicRichText.vue

@@ -0,0 +1,130 @@
+<script lang="ts" setup>
+// TODO: Remove in v6
+import { asHTML, isFilled } from "@prismicio/client"
+import { DEV } from "esm-env"
+import type { Component } from "vue"
+import {
+	computed,
+	inject,
+	nextTick,
+	onBeforeUnmount,
+	onMounted,
+	ref,
+	watch,
+} from "vue"
+import { routerKey } from "vue-router"
+
+import { devMsg } from "../lib/devMsg"
+import { isInternalURL } from "../lib/isInternalURL"
+
+import { usePrismic } from "../usePrismic"
+
+import type { PrismicRichTextProps } from "./PrismicRichText.vue"
+
+/**
+ * The default component rendered to wrap the HTML output.
+ */
+const defaultWrapper = "div"
+
+const props = defineProps<
+	Pick<
+		PrismicRichTextProps,
+		"field" | "linkResolver" | "serializer" | "wrapper"
+	> & { fallback?: string }
+>()
+defineOptions({ name: "DeprecatedPrismicRichText" })
+
+const { options } = usePrismic()
+
+if (DEV) {
+	onMounted(() => {
+		console.warn(
+			`[PrismicRichText] You're using the deprecated version of \`<PrismicRichText>\` because either the \`serializer\` prop or the plugin \`richTextSerializer\` option were provided. This API will be removed in a future major. For more details, see ${devMsg(
+				"html-serialization-is-deprecated-with-prismic-rich-text.md",
+			)}`,
+		)
+	})
+}
+
+const html = computed(() => {
+	if (!isFilled.richText(props.field)) {
+		return props.fallback ?? ""
+	}
+
+	const linkResolver = props.linkResolver ?? options.linkResolver
+	const serializer = props.serializer ?? options.richTextSerializer
+
+	return asHTML(props.field, { linkResolver, serializer })
+})
+
+// Internal links handling
+const root = ref<HTMLElement | Comment | Component | null>(null)
+
+const maybeRouter = inject(routerKey, null)
+
+type InternalLink = {
+	element: HTMLAnchorElement
+	listener: EventListener
+}
+
+let links: InternalLink[] = []
+
+const navigate: EventListener = function (
+	this: { href: string },
+	event: Event,
+) {
+	event.preventDefault()
+	maybeRouter?.push(this.href)
+}
+
+const addListeners = () => {
+	const node: HTMLElement | Comment | null =
+		root.value && "$el" in root.value ? root.value.$el : root.value
+	if (node && "querySelectorAll" in node) {
+		// Get all internal link tags and add listeners on them
+		links = Array.from(node.querySelectorAll("a"))
+			.map((element) => {
+				const href = element.getAttribute("href")
+
+				if (href && isInternalURL(href)) {
+					const listener = navigate.bind({ href })
+					element.addEventListener("click", listener)
+
+					return { element, listener }
+				} else {
+					return false
+				}
+			})
+			.filter((link): link is InternalLink => link as boolean)
+	}
+}
+
+const removeListeners = () => {
+	links.forEach(({ element, listener }) =>
+		element.removeEventListener("click", listener),
+	)
+	links = []
+}
+
+watch(
+	html,
+	() => {
+		removeListeners()
+		nextTick(addListeners)
+	},
+	{ immediate: true },
+)
+
+onBeforeUnmount(() => {
+	removeListeners()
+})
+</script>
+
+<template>
+	<component
+		v-if="isFilled.richText(field) || fallback"
+		ref="root"
+		:is="wrapper || defaultWrapper"
+		v-html="html"
+	/>
+</template>

package/src/PrismicRichText/PrismicRichText.vue

@@ -0,0 +1,157 @@
+<script lang="ts" setup>
+import {
+	type HTMLRichTextFunctionSerializer,
+	type HTMLRichTextMapSerializer,
+	type LinkResolverFunction,
+	type RichTextField,
+	isFilled,
+} from "@prismicio/client"
+import { asTree } from "@prismicio/client/richtext"
+import { DEV } from "esm-env"
+import { computed, watchEffect } from "vue"
+
+import Wrapper from "../lib/Wrapper.vue"
+
+import type { ComponentOrTagName } from "../types"
+import type { VueRichTextSerializer } from "./types"
+
+import { usePrismic } from "../usePrismic"
+
+import DeprecatedPrismicRichText from "./DeprecatedPrismicRichText.vue"
+import PrismicRichTextSerialize from "./PrismicRichTextSerialize.vue"
+
+/**
+ * Props for `<PrismicRichText />`.
+ */
+export type PrismicRichTextProps = {
+	/**
+	 * The Prismic rich text or title field to render.
+	 */
+	field: RichTextField | null | undefined
+
+	/**
+	 * The value to be rendered when the field is empty. If a fallback is not
+	 * given, `null` (nothing) will be rendered.
+	 */
+	fallback?: ComponentOrTagName
+
+	/**
+	 * An object that maps a rich text block type to a Vue component.
+	 *
+	 * @example
+	 *
+	 * ```javascript
+	 * {
+	 *   heading1: Heading1,
+	 * }
+	 * ```
+	 */
+	components?: VueRichTextSerializer
+
+	/**
+	 * A link resolver function used to resolve link when not using the route
+	 * resolver parameter with `@prismicio/client`.
+	 *
+	 * @defaultValue The link resolver provided to `@prismicio/vue` plugin if configured.
+	 *
+	 * @see Link resolver documentation {@link https://prismic.io/docs/core-concepts/link-resolver-route-resolver#link-resolver}
+	 */
+	linkResolver?: LinkResolverFunction
+
+	/**
+	 * An HTML serializer to customize the way rich text fields are rendered.
+	 *
+	 * @deprecated Use `components` instead.
+	 *
+	 * @defaultValue The HTML serializer provided to `@prismicio/vue` plugin if configured.
+	 *
+	 * @see HTML serializer documentation {@link https://prismic.io/docs/core-concepts/html-serializer}
+	 */
+	// TODO: Remove in v6
+	serializer?: HTMLRichTextFunctionSerializer | HTMLRichTextMapSerializer
+
+	/**
+	 * An HTML tag name or a component used to wrap the output. `<PrismicText />`
+	 * is not wrapped by default.
+	 *
+	 * @defaultValue `"template"` (no wrapper)
+	 */
+	wrapper?: ComponentOrTagName
+}
+
+const props = defineProps<PrismicRichTextProps>()
+defineOptions({ name: "PrismicRichText" })
+
+const { options } = usePrismic()
+
+const resolvedComponents = computed(() => {
+	return props.components || options.components?.richTextComponents
+})
+
+const resolvedLinkResolver = computed(() => {
+	return props.linkResolver || options.linkResolver
+})
+
+const children = computed(() => {
+	return asTree(props.field || []).children
+})
+
+const isModern = computed(() => {
+	// Explicit components prop
+	if (props.components) {
+		return true
+	}
+
+	// Explicit serializer prop
+	if (props.serializer) {
+		return false
+	}
+
+	// Global components option
+	if (options.components?.richTextComponents) {
+		return true
+	}
+
+	// Global serializer option
+	if (options.richTextSerializer) {
+		return false
+	}
+
+	// Default to modern
+	return true
+})
+
+if (DEV) {
+	watchEffect(() => {
+		// TODO: Remove in v6
+		if (props.components && props.serializer) {
+			console.warn(
+				`[PrismicRichText] Only one of "components" or "serializer" (deprecated) props can be provided. You can resolve this warning by removing either the "components" or "serializer" prop. "components" will be used in this case.`,
+			)
+		}
+	})
+}
+</script>
+
+<template>
+	<Wrapper
+		v-if="isModern && (isFilled.richText(field) || fallback)"
+		:wrapper="wrapper"
+	>
+		<PrismicRichTextSerialize
+			v-if="children.length"
+			:children="children"
+			:components="resolvedComponents"
+			:link-resolver="resolvedLinkResolver"
+		/>
+		<component v-else :is="fallback" />
+	</Wrapper>
+	<DeprecatedPrismicRichText
+		v-else-if="!isModern"
+		:field="field"
+		:fallback="typeof fallback === 'string' ? fallback : undefined"
+		:link-resolver="linkResolver"
+		:serializer="serializer"
+		:wrapper="wrapper"
+	/>
+</template>

package/src/PrismicRichText/PrismicRichTextDefaultComponent.vue

@@ -0,0 +1,63 @@
+<script lang="ts" setup>
+import type { LinkResolverFunction } from "@prismicio/client"
+import { computed } from "vue"
+
+import type { RichTextComponentProps } from "./types"
+
+import PrismicEmbed from "../PrismicEmbed.vue"
+import PrismicImage from "../PrismicImage.vue"
+import PrismicLink from "../PrismicLink.vue"
+
+const props = defineProps<
+	RichTextComponentProps & {
+		linkResolver?: LinkResolverFunction
+	}
+>()
+defineOptions({ name: "PrismicRichTextDefaultComponent" })
+
+const dir = computed(() => {
+	return "direction" in props.node && props.node.direction === "rtl"
+		? "rtl"
+		: undefined
+})
+</script>
+
+<template>
+	<h1 v-if="node.type === 'heading1'" :dir="dir"><slot /></h1>
+	<h2 v-else-if="node.type === 'heading2'" :dir="dir"><slot /></h2>
+	<h3 v-else-if="node.type === 'heading3'" :dir="dir"><slot /></h3>
+	<h4 v-else-if="node.type === 'heading4'" :dir="dir"><slot /></h4>
+	<h5 v-else-if="node.type === 'heading5'" :dir="dir"><slot /></h5>
+	<h6 v-else-if="node.type === 'heading6'" :dir="dir"><slot /></h6>
+	<p v-else-if="node.type === 'paragraph'" :dir="dir"><slot /></p>
+	<pre v-else-if="node.type === 'preformatted'"><slot /></pre>
+	<strong v-else-if="node.type === 'strong'"><slot /></strong>
+	<em v-else-if="node.type === 'em'"><slot /></em>
+	<li v-else-if="node.type === 'list-item'" :dir="dir"><slot /></li>
+	<li v-else-if="node.type === 'o-list-item'" :dir="dir"><slot /></li>
+	<ul v-else-if="node.type === 'group-list-item'">
+		<slot />
+	</ul>
+	<ol v-else-if="node.type === 'group-o-list-item'">
+		<slot />
+	</ol>
+	<p class="block-img" v-else-if="node.type === 'image'">
+		<PrismicLink v-if="node.linkTo" :field="node.linkTo"
+			><PrismicImage :field="node"
+		/></PrismicLink>
+		<PrismicImage v-else :field="node" />
+	</p>
+	<PrismicEmbed v-else-if="node.type === 'embed'" :field="node.oembed" />
+	<PrismicLink
+		v-else-if="node.type === 'hyperlink'"
+		:field="node.data"
+		:link-resolver="linkResolver"
+		><slot
+	/></PrismicLink>
+	<span v-else-if="node.type === 'label'" :class="node.data.label"
+		><slot
+	/></span>
+	<template v-else v-for="(line, index) in node.text.split('\n')" :key="line"
+		><br v-if="index > 0" />{{ line }}</template
+	>
+</template>

package/src/PrismicRichText/PrismicRichTextSerialize.vue

@@ -0,0 +1,52 @@
+<script lang="ts" setup>
+import type { LinkResolverFunction } from "@prismicio/client"
+import type { asTree } from "@prismicio/client/richtext"
+
+import type { VueRichTextSerializer } from "./types"
+
+import PrismicRichTextDefaultComponent from "./PrismicRichTextDefaultComponent.vue"
+
+const CHILD_TYPE_RENAMES = {
+	"list-item": "listItem",
+	"o-list-item": "oListItem",
+	"group-list-item": "list",
+	"group-o-list-item": "oList",
+} as const
+
+type PrismicRichTextSerializeProps = {
+	components?: VueRichTextSerializer
+	children: ReturnType<typeof asTree>["children"]
+	linkResolver?: LinkResolverFunction
+}
+
+const props = defineProps<PrismicRichTextSerializeProps>()
+defineOptions({ name: "PrismicRichTextSerialize" })
+
+function getComponent(child: ReturnType<typeof asTree>["children"][number]) {
+	return (
+		props.components?.[
+			CHILD_TYPE_RENAMES[child.type as keyof typeof CHILD_TYPE_RENAMES] ||
+				(child.type as keyof typeof props.components)
+		] || PrismicRichTextDefaultComponent
+	)
+}
+</script>
+
+<template>
+	<component
+		v-for="child in props.children"
+		:key="JSON.stringify(child)"
+		:is="getComponent(child)"
+		:node="child.node"
+		:link-resolver="
+			getComponent(child) === PrismicRichTextDefaultComponent
+				? props.linkResolver
+				: undefined
+		"
+		><PrismicRichTextSerialize
+			v-if="child.children.length"
+			:children="child.children"
+			:components="components"
+			:link-resolver="linkResolver"
+	/></component>
+</template>

package/src/PrismicRichText/getRichTextComponentProps.ts

@@ -0,0 +1,63 @@
+import type { RTAnyNode } from "@prismicio/client"
+import type { PropType } from "vue"
+
+import type { RichTextComponentProps } from "./types"
+
+/**
+ * Native Vue props for a component rendering nodes from a Prismic rich text
+ * field using the `<PrismicRichText />` component.
+ *
+ * @typeParam TRTNode - The type of rich text node(s) this component handles
+ */
+type DefineComponentRichTextComponentProps<
+	TRTNode extends RTAnyNode = RTAnyNode,
+> = {
+	node: {
+		type: PropType<RichTextComponentProps<TRTNode>["node"]>
+		required: true
+	}
+}
+
+/**
+ * Gets native Vue props for a component rendering nodes from a Prismic rich
+ * text field using the `<PrismicRichText />` component.
+ *
+ * Props are: `["node"]`
+ *
+ * @example
+ *
+ * ```javascript
+ * // Defining a new rich text component
+ * import { getRichTextComponentProps } from "@prismicio/vue"
+ *
+ * defineProps(getRichTextComponentProps())
+ * ```
+ *
+ * @example
+ *
+ * ```typescript
+ * // Defining a new rich text component for a specific node type
+ * import { getRichTextComponentProps } from "@prismicio/vue"
+ *
+ * defineProps(getRichTextComponentProps("heading1"))
+ * ```
+ *
+ * @typeParam TRTType - The type of rich text node(s) this component handles
+ *
+ * @param type - The type of rich text node this component handles
+ *
+ * @returns Props object to use with `defineProps()`
+ */
+export const getRichTextComponentProps = <TRTType extends RTAnyNode["type"]>(
+	// eslint-disable-next-line @typescript-eslint/no-unused-vars
+	type?: TRTType,
+): DefineComponentRichTextComponentProps<
+	Extract<RTAnyNode, { type: TRTType }>
+> => ({
+	node: {
+		type: Object as PropType<
+			RichTextComponentProps<Extract<RTAnyNode, { type: TRTType }>>["node"]
+		>,
+		required: true,
+	},
+})

package/src/PrismicRichText/index.ts

@@ -0,0 +1,3 @@
+export { getRichTextComponentProps } from "./getRichTextComponentProps"
+
+export type { VueRichTextSerializer, RichTextComponentProps } from "./types"

package/src/PrismicRichText/types.ts

@@ -0,0 +1,37 @@
+import type { RTAnyNode, RichTextNodeType } from "@prismicio/client"
+import type {
+	DefineComponent,
+	FunctionalComponent,
+	defineAsyncComponent,
+} from "vue"
+
+/**
+ * A map of Rich Text block types to Vue Components. It is used to render Rich
+ * Text or title fields.
+ *
+ * @see Templating Rich Text and title fields from Prismic {@link https://prismic.io/docs/rich-text}
+ */
+export type VueRichTextSerializer = Partial<
+	Record<keyof typeof RichTextNodeType, VueRichTextComponent>
+>
+
+/**
+ * Props for a component rendering nodes from a Prismic rich text field.
+ */
+export type RichTextComponentProps<TRTNode extends RTAnyNode = RTAnyNode> = {
+	node: TRTNode
+}
+
+/**
+ * A Vue component rendering a node from a Prismic rich text field.
+ *
+ * @typeParam TRTNode - The type of rich text node(s) this component handles
+ */
+type VueRichTextComponent<TRTNode extends RTAnyNode = RTAnyNode> =
+	// For reference within TypeScript files when `*.vue` type cannot be inferred
+	// eslint-disable-next-line @typescript-eslint/no-empty-object-type, @typescript-eslint/no-explicit-any
+	| DefineComponent<{}, {}, any>
+	// Likewise, for reference with TypeScript files.
+	| ReturnType<typeof defineAsyncComponent>
+	| DefineComponent<RichTextComponentProps<TRTNode>>
+	| FunctionalComponent<RichTextComponentProps<TRTNode>>