@prismicio/vue 3.0.0-alpha.5 → 3.0.0-beta.2

package/src/components/PrismicImage.ts

@@ -3,15 +3,24 @@ import {
 	ComponentCustomProps,
 	computed,
 	ConcreteComponent,
+	ComputedRef,
 	defineComponent,
 	h,
 	PropType,
 	VNodeProps,
+	unref,
 } from "vue";
 
 import { ImageField } from "@prismicio/types";
+import {
+	asImageSrc,
+	asImageWidthSrcSet,
+	asImagePixelDensitySrcSet,
+	isFilled,
+} from "@prismicio/helpers";
 
 import { usePrismic } from "../usePrismic";
+import { VueUseOptions } from "../types";
 import { simplyResolveComponent } from "../lib/simplyResolveComponent";
 
 /**
@@ -33,17 +42,165 @@ export type PrismicImageProps = {
 	 *
 	 * @remarks
 	 * HTML tag names and components will be rendered using the `img` tag
-	 * interface (`src` and `alt` attribute). Components will also receive an
-	 * additional `copyright` props.
+	 * interface (`src`, `srcset`, and `alt` attribute). Components will also
+	 * receive an additional `copyright` props.
 	 * @defaultValue The one provided to `@prismicio/vue` plugin if configured, `"img"` otherwise.
 	 */
 	imageComponent?: string | ConcreteComponent;
 
 	/**
-	 * A map of additional props to pass to the component used to render images
-	 * when using one.
+	 * An object of Imgix URL API parameters.
+	 *
+	 * @see Imgix URL parameters reference: https://docs.imgix.com/apis/rendering
+	 */
+	imgixParams?: Parameters<typeof asImageSrc>[1];
+
+	/**
+	 * Adds an additional `srcset` attribute to the image following given widths.
+	 *
+	 * @remarks
+	 * A special value of `"auto"` is accepted to automatically use image widths
+	 * coming from the API.
+	 * @remarks
+	 * A special value of `"defaults"` is accepted to automatically use image
+	 * widths coming from `@prismicio/helpers`
+	 * @remarks
+	 * This prop is not compatible with the `pixelDensities` prop. When both are
+	 * used the `pixelDensities` prop will be ignored.
+	 */
+	widths?:
+		| NonNullable<Parameters<typeof asImageWidthSrcSet>[1]>["widths"]
+		| "auto"
+		| "defaults";
+
+	/**
+	 * Adds an additional `srcset` attribute to the image following giving pixel densities.
+	 *
+	 * @remarks
+	 * A special value of `"defaults"` is accepted to automatically use image
+	 * pixel densities coming from `@prismicio/helpers`
+	 * @remarks
+	 * This prop is not compatible with the `widths` prop. When both are used, the
+	 * `pixelDensities` prop will be ignored.
+	 */
+	pixelDensities?:
+		| NonNullable<
+				Parameters<typeof asImagePixelDensitySrcSet>[1]
+		  >["pixelDensities"]
+		| "defaults";
+};
+
+/**
+ * Options for {@link usePrismicImage}.
+ */
+export type UsePrismicImageOptions = VueUseOptions<
+	Omit<PrismicImageProps, "imageComponent">
+>;
+
+/**
+ * Return type of {@link usePrismicImage}.
+ */
+export type UsePrismicImageReturnType = {
+	/**
+	 * Resolved image `src` value.
+	 */
+	src: ComputedRef<string | null>;
+
+	/**
+	 * Resolved image `srcset` value.
+	 */
+	srcset: ComputedRef<string | null>;
+
+	/**
+	 * Resolved image `alt` value.
 	 */
-	imageComponentAdditionalProps?: Record<string, unknown>;
+	alt: ComputedRef<string | null>;
+
+	/**
+	 * Resolved image `copyright` value.
+	 */
+	copyright: ComputedRef<string | null>;
+};
+
+/**
+ * A low level composable that returns a resolved information about a Prismic image field.
+ *
+ * @param props - {@link UsePrismicImageOptions}
+ *
+ * @returns - Resolved image information {@link UsePrismicImageReturnType}
+ */
+export const usePrismicImage = (
+	props: UsePrismicImageOptions,
+): UsePrismicImageReturnType => {
+	const asImage = computed(() => {
+		const field = unref(props.field);
+
+		if (!isFilled.image(field)) {
+			return {
+				src: null,
+				srcset: null,
+			};
+		}
+
+		const imgixParams = unref(props.imgixParams);
+		const widths = unref(props.widths);
+		const pixelDensities = unref(props.pixelDensities);
+
+		if (widths) {
+			if (pixelDensities) {
+				console.warn(
+					"[PrismicImage] `widths` and `pixelDensities` props should not be use alongside each others, only `widths` will be applied",
+					props,
+				);
+			}
+
+			if (widths === "auto") {
+				return asImageWidthSrcSet(field, imgixParams);
+			} else {
+				// Remove potential thumbnails when using manual widths
+				const { url, dimensions, alt, copyright } = field;
+
+				return asImageWidthSrcSet(
+					{ url, dimensions, alt, copyright },
+					{
+						...imgixParams,
+						widths: widths === "defaults" ? undefined : widths,
+					},
+				);
+			}
+		} else if (pixelDensities) {
+			return asImagePixelDensitySrcSet(field, {
+				...imgixParams,
+				pixelDensities:
+					pixelDensities === "defaults" ? undefined : pixelDensities,
+			});
+		} else {
+			return {
+				src: asImageSrc(field, imgixParams),
+				srcset: null,
+			};
+		}
+	});
+
+	const src = computed(() => {
+		return asImage.value.src;
+	});
+	const srcset = computed(() => {
+		return asImage.value.srcset;
+	});
+	const alt = computed(() => {
+		return unref(props.field).alt || null;
+	});
+	const copyright = computed(() => {
+		return unref(props.field).copyright || null;
+	});
+
+	return {
+		src,
+		srcset,
+		alt,
+		copyright,
+	};
 };
 
 /**
@@ -63,8 +220,27 @@ export const PrismicImageImpl = /*#__PURE__*/ defineComponent({
 			default: undefined,
 			required: false,
 		},
-		imageComponentAdditionalProps: {
-			type: Object as PropType<Record<string, unknown>>,
+		imgixParams: {
+			type: Object as PropType<Parameters<typeof asImageSrc>[1]>,
+			default: undefined,
+			required: false,
+		},
+		widths: {
+			type: [String, Object] as PropType<
+				| NonNullable<Parameters<typeof asImageWidthSrcSet>[1]>["widths"]
+				| "auto"
+				| "defaults"
+			>,
+			default: undefined,
+			required: false,
+		},
+		pixelDensities: {
+			type: [String, Object] as PropType<
+				| NonNullable<
+						Parameters<typeof asImagePixelDensitySrcSet>[1]
+				  >["pixelDensities"]
+				| "defaults"
+			>,
 			default: undefined,
 			required: false,
 		},
@@ -85,10 +261,13 @@ export const PrismicImageImpl = /*#__PURE__*/ defineComponent({
 			);
 		});
 
+		const { src, srcset, alt, copyright } = usePrismicImage(props);
+
 		return () => {
 			const attributes = {
-				src: props.field.url || null,
-				alt: props.field.alt || null,
+				src: src.value,
+				srcset: srcset.value,
+				alt: alt.value,
 			};
 
 			switch (type.value) {
@@ -99,8 +278,7 @@ export const PrismicImageImpl = /*#__PURE__*/ defineComponent({
 				default:
 					return h(simplyResolveComponent(type.value), {
 						...attributes,
-						copyright: props.field.copyright || null,
-						...props.imageComponentAdditionalProps,
+						copyright: copyright.value,
 					});
 			}
 		};

package/src/components/PrismicLink.ts

@@ -50,6 +50,7 @@ export type PrismicLinkProps = {
 	 * 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;
@@ -57,19 +58,19 @@ export type PrismicLinkProps = {
 	/**
 	 * An explicit `target` attribute to apply to the rendered link.
 	 */
-	target?: string;
+	target?: string | null;
 
 	/**
 	 * An explicit `rel` attribute to apply to the rendered link.
 	 */
-	rel?: string;
+	rel?: string | null;
 
 	/**
 	 * Value of the `rel` attribute to use on links rendered with `target="_blank"`.
 	 *
 	 * @defaultValue The one provided to `@prismicio/vue` plugin if configured, `"noopener noreferrer"` otherwise.
 	 */
-	blankTargetRelAttribute?: string;
+	blankTargetRelAttribute?: string | null;
 
 	/**
 	 * An HTML tag name, a component, or a functional component used to render
@@ -165,21 +166,33 @@ export const usePrismicLink = (
 	});
 	const target = computed(() => {
 		const field = unref(props.field);
+		const target = unref(props.target);
 
-		return (
-			unref(props.target) ||
-			(field && "target" in field && field.target ? field.target : null)
-		);
+		if (typeof target !== "undefined") {
+			return target;
+		} else {
+			return field && "target" in field && field.target ? field.target : null;
+		}
 	});
 	const rel = computed(() => {
-		return (
-			unref(props.rel) ||
-			(target.value === "_blank"
-				? unref(props.blankTargetRelAttribute) ||
-				  options.components?.linkBlankTargetRelAttribute ||
-				  defaultBlankTargetRelAttribute
-				: null)
-		);
+		const rel = unref(props.rel);
+
+		if (typeof rel !== "undefined") {
+			return rel;
+		} else if (target.value === "_blank") {
+			const blankTargetRelAttribute = unref(props.blankTargetRelAttribute);
+
+			if (typeof blankTargetRelAttribute !== "undefined") {
+				return blankTargetRelAttribute;
+			} else {
+				return typeof options.components?.linkBlankTargetRelAttribute !==
+					"undefined"
+					? options.components.linkBlankTargetRelAttribute
+					: defaultBlankTargetRelAttribute;
+			}
+		} else {
+			return null;
+		}
 	});
 
 	return {
@@ -208,17 +221,17 @@ export const PrismicLinkImpl = /*#__PURE__*/ defineComponent({
 			required: false,
 		},
 		target: {
-			type: String as PropType<string>,
+			type: String as PropType<string | null>,
 			default: undefined,
 			required: false,
 		},
 		rel: {
-			type: String as PropType<string>,
+			type: String as PropType<string | null>,
 			default: undefined,
 			required: false,
 		},
 		blankTargetRelAttribute: {
-			type: String as PropType<string>,
+			type: String as PropType<string | null>,
 			default: undefined,
 			required: false,
 		},

package/src/components/PrismicRichText.ts

@@ -50,6 +50,7 @@ export type PrismicRichTextProps = {
 	 * 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;
@@ -58,6 +59,7 @@ export type PrismicRichTextProps = {
 	 * An HTML serializer to customize the way rich text fields are rendered.
 	 *
 	 * @defaultValue The HTML serializer provided to `@prismicio/vue` plugin if configured.
+	 *
 	 * @see HTML serializer documentation {@link https://prismic.io/docs/core-concepts/html-serializer}
 	 */
 	htmlSerializer?: HTMLFunctionSerializer | HTMLMapSerializer;
@@ -104,7 +106,8 @@ export const usePrismicRichText = (
 		const htmlSerializer =
 			unref(props.htmlSerializer) ?? options.htmlSerializer;
 
-		return asHTML(unref(props.field), linkResolver, htmlSerializer);
+		// TODO: Update after https://github.com/prismicio/prismic-helpers/pull/43
+		return asHTML(unref(props.field), linkResolver, htmlSerializer) || "";
 	});
 
 	return {

package/src/components/PrismicText.ts

@@ -22,7 +22,6 @@ import { simplyResolveComponent } from "../lib/simplyResolveComponent";
  * The default component rendered to wrap the text output.
  */
 const defaultWrapper = "div";
-
 /**
  * Props for `<PrismicText />`.
  */
@@ -75,7 +74,8 @@ export const usePrismicText = (
 	props: UsePrismicTextOptions,
 ): UsePrismicTextReturnType => {
 	const text = computed(() => {
-		return asText(unref(props.field), unref(props.separator));
+		// TODO: Update after https://github.com/prismicio/prismic-helpers/pull/43
+		return asText(unref(props.field), unref(props.separator)) || "";
 	});
 
 	return {

package/src/components/SliceZone.ts

@@ -149,7 +149,7 @@ export const getSliceComponentProps = <
 	TContext = unknown,
 >(
 	// eslint-disable-next-line @typescript-eslint/no-unused-vars
-	propsHint?: string[],
+	propsHint?: ["slice", "index", "slices", "context"],
 ): DefineComponentSliceComponentProps<TSlice, TContext> => ({
 	slice: {
 		type: Object as PropType<SliceComponentProps<TSlice, TContext>["slice"]>,
@@ -254,11 +254,11 @@ export type SliceZoneComponents<
  * @example Defining a slice components:
  *
  * ```javascript
- * import { getSliceZoneComponents } from "@prismicio/vue";
+ * import { defineSliceZoneComponents } from "@prismicio/vue";
  *
  * export default {
  *   data() {
- *     components: getSliceZoneComponents({
+ *     components: defineSliceZoneComponents({
  *       foo: Foo,
  *       bar: defineAsyncComponent(
  *         () => new Promise((res) => res(Bar)),
@@ -271,11 +271,12 @@ export type SliceZoneComponents<
  *
  * @typeParam TSlice - The type(s) of slices in the Slice Zone
  * @typeParam TContext - Arbitrary data made available to all Slice components
+ *
  * @param components - {@link SliceZoneComponents}
  *
  * @returns A new optimized record of {@link SliceZoneComponents}
  */
-export const getSliceZoneComponents = <
+export const defineSliceZoneComponents = <
 	TSlice extends SliceLike = SliceLike,
 	TContext = unknown,
 >(
@@ -300,6 +301,44 @@ export const getSliceZoneComponents = <
 	return result;
 };
 
+/**
+ * Arguments for a `<SliceZone>` `resolver` function.
+ */
+export type SliceZoneResolverArgs<TSlice extends SliceLike = SliceLike> = {
+	/**
+	 * The Slice to resolve to a Vue component..
+	 */
+	slice: TSlice;
+
+	/**
+	 * The name of the Slice.
+	 */
+	sliceName: TSlice["slice_type"];
+
+	/**
+	 * The index of the Slice in the Slice Zone.
+	 */
+	i: number;
+};
+
+/**
+ * A function that determines the rendered Vue component for each Slice in the
+ * Slice Zone. If a nullish value is returned, the component will fallback to
+ * the `components` or `defaultComponent` props to determine the rendered component.
+ *
+ * @deprecated Use the `components` prop instead.
+ *
+ * @param args - Arguments for the resolver function.
+ *
+ * @returns The Vue component to render for a Slice.
+ */
+export type SliceZoneResolver<
+	TSlice extends SliceLike = SliceLike,
+	TContext = unknown,
+> = (
+	args: SliceZoneResolverArgs<TSlice>,
+) => SliceComponentType<TSlice, TContext> | string | undefined | null;
+
 /**
  * Props for `<SliceZone />`.
  *
@@ -318,7 +357,19 @@ export type SliceZoneProps<
 	/**
 	 * A record mapping Slice types to Vue components.
 	 */
-	components: SliceZoneComponents;
+	components?: SliceZoneComponents;
+
+	/**
+	 * A function that determines the rendered Vue component for each Slice in the
+	 * Slice Zone.
+	 *
+	 * @deprecated Use the `components` prop instead.
+	 *
+	 * @param args - Arguments for the resolver function.
+	 *
+	 * @returns The Vue component to render for a Slice.
+	 */
+	resolver?: SliceZoneResolver<TSlice, TContext>;
 
 	/**
 	 * Arbitrary data made available to all Slice components.
@@ -331,6 +382,7 @@ export type SliceZoneProps<
 	 *
 	 * @remarks
 	 * Components will be rendered using the {@link SliceComponentProps} interface.
+	 *
 	 * @defaultValue The Slice Zone default component provided to `@prismicio/vue` plugin if configured, otherwise `null` when `process.env.NODE_ENV === "production"` else {@link TODOSliceComponent}.
 	 */
 	defaultComponent?: SliceComponentType<TSlice, TContext>;
@@ -356,7 +408,13 @@ export const SliceZoneImpl = /*#__PURE__*/ defineComponent({
 		},
 		components: {
 			type: Object as PropType<SliceZoneComponents>,
-			required: true,
+			default: undefined,
+			required: false,
+		},
+		resolver: {
+			type: Function as PropType<SliceZoneResolver>,
+			default: undefined,
+			required: false,
 		},
 		context: {
 			type: null,
@@ -384,14 +442,28 @@ export const SliceZoneImpl = /*#__PURE__*/ defineComponent({
 
 		const renderedSlices = computed(() => {
 			return props.slices.map((slice, index) => {
-				const component =
-					slice.slice_type in props.components
+				let component =
+					props.components && slice.slice_type in props.components
 						? props.components[slice.slice_type]
 						: props.defaultComponent ||
 						  options.components?.sliceZoneDefaultComponent ||
 						  TODOSliceComponent;
 
+				// TODO: Remove `resolver` in v3 in favor of `components`.
+				if (props.resolver) {
+					const resolvedComponent = props.resolver({
+						slice,
+						sliceName: slice.slice_type,
+						i: index,
+					});
+
+					if (resolvedComponent) {
+						component = resolvedComponent;
+					}
+				}
+
 				const p = {
+					key: `${slice.slice_type}-${index}`,
 					slice,
 					index,
 					context: props.context,

package/src/components/index.ts

@@ -1,8 +1,12 @@
 export { PrismicEmbedImpl, PrismicEmbed } from "./PrismicEmbed";
 export type { PrismicEmbedProps } from "./PrismicEmbed";
 
-export { PrismicImageImpl, PrismicImage } from "./PrismicImage";
-export type { PrismicImageProps } from "./PrismicImage";
+export {
+	usePrismicImage,
+	PrismicImageImpl,
+	PrismicImage,
+} from "./PrismicImage";
+export type { UsePrismicImageOptions, PrismicImageProps } from "./PrismicImage";
 
 export { usePrismicLink, PrismicLinkImpl, PrismicLink } from "./PrismicLink";
 export type { UsePrismicLinkOptions, PrismicLinkProps } from "./PrismicLink";
@@ -23,7 +27,7 @@ export type {
 export {
 	getSliceComponentProps,
 	TODOSliceComponent,
-	getSliceZoneComponents,
+	defineSliceZoneComponents,
 	SliceZoneImpl,
 	SliceZone,
 } from "./SliceZone";
@@ -33,6 +37,8 @@ export type {
 	SliceComponentType,
 	SliceLike,
 	SliceZoneComponents,
+	SliceZoneResolverArgs,
+	SliceZoneResolver,
 	SliceZoneLike,
 	SliceZoneProps,
 } from "./SliceZone";