@prismicio/react 2.2.0 → 2.4.1

package/src/PrismicImage.tsx

@@ -0,0 +1,185 @@
+import * as React from "react";
+import * as prismicT from "@prismicio/types";
+import * as prismicH from "@prismicio/helpers";
+
+import { __PRODUCTION__ } from "./lib/__PRODUCTION__";
+import { devMsg } from "./lib/devMsg";
+
+/**
+ * Props for `<PrismicImage>`.
+ */
+export type PrismicImageProps = Omit<
+	React.DetailedHTMLProps<
+		React.ImgHTMLAttributes<HTMLImageElement>,
+		HTMLImageElement
+	>,
+	"src" | "srcset" | "alt"
+> & {
+	/**
+	 * The Prismic Image field or thumbnail to render.
+	 */
+	field: prismicT.ImageFieldImage | null | undefined;
+
+	/**
+	 * An object of Imgix URL API parameters to transform the image.
+	 *
+	 * See: https://docs.imgix.com/apis/rendering
+	 */
+	imgixParams?: Parameters<typeof prismicH.asImageSrc>[1];
+
+	/**
+	 * Declare an image as decorative by providing `alt=""`.
+	 *
+	 * See:
+	 * https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/alt#decorative_images
+	 */
+	alt?: "";
+
+	/**
+	 * Declare an image as decorative only if the Image field does not have
+	 * alternative text by providing `fallbackAlt=""`.
+	 *
+	 * See:
+	 * https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/alt#decorative_images
+	 */
+	fallbackAlt?: "";
+} & (
+		| {
+				/**
+				 * Widths used to build a `srcset` value for the Image field.
+				 *
+				 * If a `widths` prop is not given or `"defaults"` is passed, the
+				 * following widths will be used: 640, 750, 828, 1080, 1200, 1920, 2048, 3840.
+				 *
+				 * If the Image field contains responsive views, each responsive view
+				 * can be used as a width in the resulting `srcset` by passing
+				 * `"thumbnails"` as the `widths` prop.
+				 */
+				widths?:
+					| NonNullable<
+							Parameters<typeof prismicH.asImageWidthSrcSet>[1]
+					  >["widths"]
+					| "defaults";
+				/**
+				 * Not used when the `widths` prop is used.
+				 */
+				pixelDensities?: never;
+		  }
+		| {
+				/**
+				 * Not used when the `widths` prop is used.
+				 */
+				widths?: never;
+				/**
+				 * Pixel densities used to build a `srcset` value for the Image field.
+				 *
+				 * If a `pixelDensities` prop is passed `"defaults"`, the following
+				 * pixel densities will be used: 1, 2, 3.
+				 */
+				pixelDensities:
+					| NonNullable<
+							Parameters<typeof prismicH.asImagePixelDensitySrcSet>[1]
+					  >["pixelDensities"]
+					| "defaults";
+		  }
+	);
+
+const _PrismicImage = (
+	props: PrismicImageProps,
+	ref: React.ForwardedRef<HTMLImageElement>,
+): JSX.Element | null => {
+	const {
+		field,
+		alt,
+		fallbackAlt,
+		imgixParams,
+		widths,
+		pixelDensities,
+		...restProps
+	} = props;
+
+	if (!__PRODUCTION__) {
+		if (typeof alt === "string" && props.alt !== "") {
+			console.warn(
+				`[PrismicImage] The "alt" prop can only be used to declare an image as decorative by passing an empty string (alt="") but was provided a non-empty string. You can resolve this warning by removing the "alt" prop or changing it to alt="". For more details, see ${devMsg(
+					"alt-must-be-an-empty-string",
+				)}`,
+			);
+		}
+
+		if (typeof fallbackAlt === "string" && fallbackAlt !== "") {
+			console.warn(
+				`[PrismicImage] The "fallbackAlt" prop can only be used to declare an image as decorative by passing an empty string (fallbackAlt="") but was provided a non-empty string. You can resolve this warning by removing the "fallbackAlt" prop or changing it to fallbackAlt="". For more details, see ${devMsg(
+					"alt-must-be-an-empty-string",
+				)}`,
+			);
+		}
+
+		if (widths && pixelDensities) {
+			console.warn(
+				`[PrismicImage] Only one of "widths" or "pixelDensities" props can be provided. You can resolve this warning by removing either the "widths" or "pixelDensities" prop. "widths" will be used in this case.`,
+			);
+		}
+	}
+
+	if (prismicH.isFilled.imageThumbnail(field)) {
+		let src: string | undefined;
+		let srcSet: string | undefined;
+
+		if (widths || !pixelDensities) {
+			const res = prismicH.asImageWidthSrcSet(field, {
+				...imgixParams,
+				widths: widths === "defaults" ? undefined : widths,
+			});
+
+			src = res.src;
+			srcSet = res.srcset;
+		} else if (pixelDensities) {
+			const res = prismicH.asImagePixelDensitySrcSet(field, {
+				...imgixParams,
+				pixelDensities:
+					pixelDensities === "defaults" ? undefined : pixelDensities,
+			});
+
+			src = res.src;
+			srcSet = res.srcset;
+		}
+
+		return (
+			<img
+				ref={ref}
+				src={src}
+				srcSet={srcSet}
+				alt={alt ?? (field.alt || fallbackAlt)}
+				{...restProps}
+			/>
+		);
+	} else {
+		return null;
+	}
+};
+
+if (!__PRODUCTION__) {
+	_PrismicImage.displayName = "PrismicImage";
+}
+
+/**
+ * React component that renders an image from a Prismic Image field or one of
+ * its thumbnails. It will automatically set the `alt` attribute using the Image
+ * field's `alt` property.
+ *
+ * By default, a widths-based srcset will be used to support responsive images.
+ * This ensures only the smallest image needed for a browser is downloaded.
+ *
+ * To use a pixel-density-based srcset, use the `pixelDensities` prop. Default
+ * pixel densities can be used by using `pixelDensities="defaults"`.
+ *
+ * **Note**: If you are using a framework that has a native image component,
+ * such as Next.js and Gatsby, prefer using those image components instead. They
+ * can provide deeper framework integration than `<PrismicImage>`.
+ *
+ * @param props - Props for the component.
+ *
+ * @returns A responsive image component for the given Image field.
+ */
+export const PrismicImage = React.forwardRef(_PrismicImage);

package/src/PrismicLink.tsx

@@ -2,6 +2,8 @@ import * as React from "react";
 import * as prismicH from "@prismicio/helpers";
 import * as prismicT from "@prismicio/types";
 
+import { __PRODUCTION__ } from "./lib/__PRODUCTION__";
+import { devMsg } from "./lib/devMsg";
 import { isInternalURL } from "./lib/isInternalURL";
 
 import { usePrismicContext } from "./usePrismicContext";
@@ -37,8 +39,8 @@ export interface LinkProps {
  * Props for `<PrismicLink>`.
  */
 export type PrismicLinkProps<
-	InternalComponent extends React.ElementType<LinkProps> = React.ElementType<LinkProps>,
-	ExternalComponent extends React.ElementType<LinkProps> = React.ElementType<LinkProps>,
+	InternalComponent extends React.ElementType<LinkProps> = typeof defaultInternalComponent,
+	ExternalComponent extends React.ElementType<LinkProps> = typeof defaultInternalComponent,
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	LinkResolverFunction extends prismicH.LinkResolverFunction<any> = prismicH.LinkResolverFunction,
 > = Omit<
@@ -118,26 +120,11 @@ const defaultInternalComponent = "a";
  */
 const defaultExternalComponent = "a";
 
-/**
- * React component that renders a link from a Prismic Link field.
- *
- * Different components can be rendered depending on whether the link is
- * internal or external. This is helpful when integrating with client-side
- * routers, such as a router-specific Link component.
- *
- * If a link is configured to open in a new window using `target="_blank"`,
- * `rel="noopener noreferrer"` is set by default.
- *
- * @param props - Props for the component.
- *
- * @returns The internal or external link component depending on whether the
- *   link is internal or external.
- */
 const _PrismicLink = <
-	InternalComponent extends React.ElementType<LinkProps>,
-	ExternalComponent extends React.ElementType<LinkProps>,
+	InternalComponent extends React.ElementType<LinkProps> = typeof defaultInternalComponent,
+	ExternalComponent extends React.ElementType<LinkProps> = typeof defaultExternalComponent,
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	LinkResolverFunction extends prismicH.LinkResolverFunction<any>,
+	LinkResolverFunction extends prismicH.LinkResolverFunction<any> = prismicH.LinkResolverFunction,
 >(
 	props: PrismicLinkProps<
 		InternalComponent,
@@ -149,6 +136,37 @@ const _PrismicLink = <
 ): JSX.Element | null => {
 	const context = usePrismicContext();
 
+	if (!__PRODUCTION__) {
+		if ("field" in props && props.field) {
+			if (
+				!("link_type" in props.field) ||
+				!("url" in props.field || "id" in props.field)
+			) {
+				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 may not render. For more details, see ${devMsg(
+						"missing-link-properties",
+					)}`,
+				);
+			}
+		} else if ("document" in props && props.document) {
+			if (!("url" in props.document || "id" in props.document)) {
+				console.error(
+					`[PrismicLink] This "document" prop value caused an error to be thrown.\n`,
+					props.document,
+				);
+				throw new Error(
+					`[PrismicLink] The provided document is missing required properties to properly render a link. The link may not render. For more details, see ${devMsg(
+						"missing-link-properties",
+					)}`,
+				);
+			}
+		}
+	}
+
 	const linkResolver = props.linkResolver || context.linkResolver;
 
 	let href: string | null | undefined;
@@ -160,12 +178,15 @@ const _PrismicLink = <
 		href = prismicH.asLink(props.field, linkResolver);
 	}
 
+	const isInternal = href && isInternalURL(href);
+
 	const target =
 		props.target ||
 		("field" in props &&
 			props.field &&
 			"target" in props.field &&
 			props.field.target) ||
+		(!isInternal && "_blank") ||
 		undefined;
 
 	const rel =
@@ -181,8 +202,6 @@ const _PrismicLink = <
 		context.externalLinkComponent ||
 		defaultExternalComponent;
 
-	const isInternal = href && isInternalURL(href);
-
 	const Component = isInternal ? InternalComponent : ExternalComponent;
 
 	const passthroughProps: typeof props = Object.assign({}, props);
@@ -215,11 +234,30 @@ const _PrismicLink = <
 	) : null;
 };
 
+if (!__PRODUCTION__) {
+	_PrismicLink.displayName = "PrismicLink";
+}
+
+/**
+ * React component that renders a link from a Prismic Link field.
+ *
+ * Different components can be rendered depending on whether the link is
+ * internal or external. This is helpful when integrating with client-side
+ * routers, such as a router-specific Link component.
+ *
+ * If a link is configured to open in a new window using `target="_blank"`,
+ * `rel="noopener noreferrer"` is set by default.
+ *
+ * @param props - Props for the component.
+ *
+ * @returns The internal or external link component depending on whether the
+ *   link is internal or external.
+ */
 export const PrismicLink = React.forwardRef(_PrismicLink) as <
-	InternalComponent extends React.ElementType<LinkProps>,
-	ExternalComponent extends React.ElementType<LinkProps>,
+	InternalComponent extends React.ElementType<LinkProps> = typeof defaultInternalComponent,
+	ExternalComponent extends React.ElementType<LinkProps> = typeof defaultExternalComponent,
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	LinkResolverFunction extends prismicH.LinkResolverFunction<any>,
+	LinkResolverFunction extends prismicH.LinkResolverFunction<any> = prismicH.LinkResolverFunction,
 >(
 	props: PrismicLinkProps<
 		InternalComponent,

package/src/PrismicText.tsx

@@ -2,6 +2,9 @@ import * as React from "react";
 import * as prismicT from "@prismicio/types";
 import * as prismicH from "@prismicio/helpers";
 
+import { __PRODUCTION__ } from "./lib/__PRODUCTION__";
+import { devMsg } from "./lib/devMsg";
+
 /**
  * Props for `<PrismicText>`.
  */
@@ -42,6 +45,16 @@ export type PrismicTextProps = {
  * @see Learn about Rich Text fields {@link https://prismic.io/docs/core-concepts/rich-text-title}
  */
 export const PrismicText = (props: PrismicTextProps): JSX.Element | null => {
+	if (!__PRODUCTION__) {
+		if (typeof props.field === "string") {
+			throw new Error(
+				`[PrismicText] The "field" prop only accepts a Rich Text or Title field's value but was provided a different type of field instead (e.g. a Key Text or Select field). You can resolve this error by rendering the field value inline without <PrismicText>. For more details, see ${devMsg(
+					"prismictext-works-only-with-rich-text-and-title-fields",
+				)}`,
+			);
+		}
+	}
+
 	return React.useMemo(() => {
 		if (prismicH.isFilled.richText(props.field)) {
 			const text = prismicH.asText(props.field, props.separator);

package/src/PrismicToolbar.tsx

@@ -43,6 +43,19 @@ export const PrismicToolbar = ({
 			script.dataset.repositoryName = repositoryName;
 			script.dataset.type = type;
 
+			// Disable Happy DOM `<script>` evaluation during
+			// tests.
+			//
+			// This is a patch ONLY INCLUDED DURING TESTS. It will
+			// be pruned during code minification in non-test
+			// environments.
+			//
+			// @see https://github.com/capricorn86/happy-dom/blob/02ae081e36f990c06171eda44f9d885fd9413d73/packages/happy-dom/src/nodes/html-script-element/HTMLScriptElement.ts#L191-L209
+			if (process.env.NODE_ENV === "test") {
+				// @ts-expect-error - `_evaluateScript` is a Happy DOM-specific property.
+				script._evaluateScript = false;
+			}
+
 			document.body.appendChild(script);
 		}
 	}, [repositoryName, type, src]);

package/src/index.ts

@@ -25,6 +25,9 @@ export { Element };
 // TODO: Remove in v3.
 export const Elements = Element;
 
+export { PrismicImage } from "./PrismicImage";
+export type { PrismicImageProps } from "./PrismicImage";
+
 export { SliceZone, TODOSliceComponent } from "./SliceZone";
 export type {
 	SliceComponentProps,

package/src/lib/devMsg.ts

@@ -0,0 +1,20 @@
+import { version } from "../../package.json";
+
+/**
+ * Returns a `prismic.dev/msg` URL for a given message slug.
+ *
+ * @example
+ *
+ * ```ts
+ * devMsg("missing-param");
+ * // => "https://prismic.dev/msg/react/v1.2.3/missing-param.md"
+ * ```
+ *
+ * @param slug - Slug for the message. This corresponds to a Markdown file in
+ *   the Git repository's `/messages` directory.
+ *
+ * @returns The `prismic.dev/msg` URL for the given slug.
+ */
+export const devMsg = (slug: string) => {
+	return `https://prismic.dev/msg/react/v${version}/${slug}`;
+};