@prismicio/react 2.2.0 → 2.3.0

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=""). 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=""). 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. "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,7 @@ import * as React from "react";
 import * as prismicH from "@prismicio/helpers";
 import * as prismicT from "@prismicio/types";
 
+import { __PRODUCTION__ } from "./lib/__PRODUCTION__";
 import { isInternalURL } from "./lib/isInternalURL";
 
 import { usePrismicContext } from "./usePrismicContext";
@@ -37,8 +38,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 +119,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,
@@ -215,11 +201,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/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}`;
+};