@prismicio/react 2.1.2-alpha.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,9 +38,10 @@ 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>,
-	LinkResolverFunction extends prismicH.LinkResolverFunction = prismicH.LinkResolverFunction,
+	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<
 	React.ComponentPropsWithoutRef<InternalComponent> &
 		React.ComponentPropsWithoutRef<ExternalComponent>,
@@ -117,25 +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> = typeof defaultInternalComponent,
 	ExternalComponent extends React.ElementType<LinkProps> = typeof defaultExternalComponent,
-	LinkResolverFunction extends prismicH.LinkResolverFunction = prismicH.LinkResolverFunction,
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	LinkResolverFunction extends prismicH.LinkResolverFunction<any> = prismicH.LinkResolverFunction,
 >(
 	props: PrismicLinkProps<
 		InternalComponent,
@@ -213,10 +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>,
-	LinkResolverFunction extends prismicH.LinkResolverFunction,
+	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> = prismicH.LinkResolverFunction,
 >(
 	props: PrismicLinkProps<
 		InternalComponent,

package/src/PrismicProvider.tsx

@@ -10,7 +10,10 @@ import { JSXFunctionSerializer, JSXMapSerializer } from "./types";
  * React context value containing shared configuration for `@prismicio/react`
  * components and hooks.
  */
-export type PrismicContextValue = {
+export type PrismicContextValue<
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	LinkResolverFunction extends prismicH.LinkResolverFunction<any> = prismicH.LinkResolverFunction,
+> = {
 	/**
 	 * A `@prismicio/client` instance used to fetch content from a Prismic
 	 * repository. This is used by `@prismicio/react` hooks, such as
@@ -26,7 +29,7 @@ export type PrismicContextValue = {
 	 * repository's content, a Link Resolver does not need to be provided.
 	 * @see Learn about Link Resolvers and Route Resolvers {@link https://prismic.io/docs/core-concepts/link-resolver-route-resolver}
 	 */
-	linkResolver?: prismicH.LinkResolverFunction;
+	linkResolver?: LinkResolverFunction;
 
 	/**
 	 * A map or function that maps a Rich Text block to a React component.
@@ -81,7 +84,9 @@ export const PrismicContext = React.createContext<PrismicContextValue>({});
 /**
  * Props for `<PrismicProvider>`.
  */
-export type PrismicProviderProps = PrismicContextValue;
+export type PrismicProviderProps<
+	LinkResolverFunction extends prismicH.LinkResolverFunction,
+> = PrismicContextValue<LinkResolverFunction>;
 
 /**
  * React context provider to share configuration for `@prismicio/react`
@@ -89,15 +94,18 @@ export type PrismicProviderProps = PrismicContextValue;
  *
  * @returns A React context provider with shared configuration.
  */
-export const PrismicProvider = ({
+export const PrismicProvider = <
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	LinkResolverFunction extends prismicH.LinkResolverFunction<any>,
+>({
 	client,
 	linkResolver,
 	richTextComponents,
 	internalLinkComponent,
 	externalLinkComponent,
 	children,
-}: PrismicProviderProps): JSX.Element => {
-	const value = React.useMemo<PrismicContextValue>(
+}: PrismicProviderProps<LinkResolverFunction>): JSX.Element => {
+	const value = React.useMemo<PrismicContextValue<LinkResolverFunction>>(
 		() => ({
 			client,
 			linkResolver,

package/src/PrismicRichText.tsx

@@ -13,7 +13,10 @@ import { usePrismicContext } from "./usePrismicContext";
 /**
  * Props for `<PrismicRichText>`.
  */
-export type PrismicRichTextProps = {
+export type PrismicRichTextProps<
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	LinkResolverFunction extends prismicH.LinkResolverFunction<any> = prismicH.LinkResolverFunction,
+> = {
 	/**
 	 * The Prismic Rich Text field to render.
 	 */
@@ -27,7 +30,7 @@ export type PrismicRichTextProps = {
 	 * repository's content, a Link Resolver does not need to be provided.
 	 * @see Learn about Link Resolvers and Route Resolvers {@link https://prismic.io/docs/core-concepts/link-resolver-route-resolver}
 	 */
-	linkResolver?: PrismicLinkProps["linkResolver"];
+	linkResolver?: LinkResolverFunction;
 
 	/**
 	 * A function that maps a Rich Text block to a React component.
@@ -58,7 +61,7 @@ export type PrismicRichTextProps = {
 	 * (type, node, content, children) => {
 	 * 	switch (type) {
 	 * 		case "heading1": {
-	 * 			return <Heading>{chidlren}</Heading>;
+	 * 			return <Heading>{children}</Heading>;
 	 * 		}
 	 * 	}
 	 * };
@@ -79,10 +82,19 @@ export type PrismicRichTextProps = {
 	 * @defaultValue `<a>`
 	 */
 	externalLinkComponent?: PrismicLinkProps["externalComponent"];
+
+	/**
+	 * The value to be rendered when the field is empty. If a fallback is not
+	 * given, `null` will be rendered.
+	 */
+	fallback?: React.ReactNode;
 };
 
-type CreateDefaultSerializerArgs = {
-	linkResolver: prismicH.LinkResolverFunction<string> | undefined;
+type CreateDefaultSerializerArgs<
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	LinkResolverFunction extends prismicH.LinkResolverFunction<any> = prismicH.LinkResolverFunction,
+> = {
+	linkResolver: LinkResolverFunction | undefined;
 	internalLinkComponent: PrismicRichTextProps["internalLinkComponent"];
 	externalLinkComponent: PrismicRichTextProps["externalLinkComponent"];
 };
@@ -214,8 +226,11 @@ const createDefaultSerializer = (
  * @see Learn about Rich Text fields {@link https://prismic.io/docs/core-concepts/rich-text-title}
  * @see Learn about Rich Text serializers {@link https://prismic.io/docs/core-concepts/html-serializer}
  */
-export const PrismicRichText = (
-	props: PrismicRichTextProps,
+export const PrismicRichText = <
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	LinkResolverFunction extends prismicH.LinkResolverFunction<any> = prismicH.LinkResolverFunction,
+>(
+	props: PrismicRichTextProps<LinkResolverFunction>,
 ): JSX.Element | null => {
 	const context = usePrismicContext();
 
@@ -255,7 +270,7 @@ export const PrismicRichText = (
 
 			return <>{serialized}</>;
 		} else {
-			return null;
+			return props.fallback != null ? <>{props.fallback}</> : null;
 		}
 	}, [
 		props.field,
@@ -263,6 +278,7 @@ export const PrismicRichText = (
 		props.externalLinkComponent,
 		props.components,
 		props.linkResolver,
+		props.fallback,
 		context.linkResolver,
 		context.richTextComponents,
 	]);

package/src/SliceZone.tsx

@@ -4,24 +4,57 @@ import * as prismicT from "@prismicio/types";
 import { __PRODUCTION__ } from "./lib/__PRODUCTION__";
 import { pascalCase, PascalCase } from "./lib/pascalCase";
 
+/**
+ * Returns the type of a `SliceLike` type.
+ *
+ * @typeParam Slice - The Slice from which the type will be extracted.
+ */
+type ExtractSliceType<Slice extends SliceLike> = Slice extends SliceLikeRestV2
+	? Slice["slice_type"]
+	: Slice extends SliceLikeGraphQL
+	? Slice["type"]
+	: never;
+
+/**
+ * The minimum required properties to represent a Prismic Slice from the Prismic
+ * Rest API V2 for the `<SliceZone>` component.
+ *
+ * If using Prismic's Rest API V2, use the `Slice` export from
+ * `@prismicio/types` for a full interface.
+ *
+ * @typeParam SliceType - Type name of the Slice.
+ */
+export type SliceLikeRestV2<SliceType extends string = string> = {
+	slice_type: prismicT.Slice<SliceType>["slice_type"];
+};
+
+/**
+ * The minimum required properties to represent a Prismic Slice from the Prismic
+ * GraphQL API for the `<SliceZone>` component.
+ *
+ * @typeParam SliceType - Type name of the Slice.
+ */
+export type SliceLikeGraphQL<SliceType extends string = string> = {
+	type: prismicT.Slice<SliceType>["slice_type"];
+};
+
 /**
  * The minimum required properties to represent a Prismic Slice for the
  * `<SliceZone>` component.
  *
- * If using Prismic's REST API, use the `Slice` export from `@prismicio/types`
- * for a full interface.
+ * If using Prismic's Rest API V2, use the `Slice` export from
+ * `@prismicio/types` for a full interface.
  *
  * @typeParam SliceType - Type name of the Slice.
  */
-export type SliceLike<SliceType extends string = string> = Pick<
-	prismicT.Slice<SliceType>,
-	"slice_type"
->;
+export type SliceLike<SliceType extends string = string> =
+	| SliceLikeRestV2<SliceType>
+	| SliceLikeGraphQL<SliceType>;
 
 /**
  * A looser version of the `SliceZone` type from `@prismicio/types` using `SliceLike`.
  *
- * If using Prismic's REST API, use the `SliceZone` export from
+ * If using Prismic's Rest API V2, use the `SliceZone` export from
  * `@prismicio/types` for the full type.
  *
  * @typeParam TSlice - The type(s) of a Slice in the Slice Zone.
@@ -97,10 +130,7 @@ export type SliceZoneComponents<
 	// signals to future developers that it is a placeholder and should be
 	// implemented.
 	{
-		[SliceType in keyof Record<
-			TSlice["slice_type"],
-			never
-		>]: SliceComponentType<
+		[SliceType in ExtractSliceType<TSlice>]: SliceComponentType<
 			Extract<TSlice, SliceLike<SliceType>> extends never
 				? SliceLike
 				: Extract<TSlice, SliceLike<SliceType>>,
@@ -119,19 +149,18 @@ export const TODOSliceComponent = __PRODUCTION__
 	: <TSlice extends SliceLike, TContext>({
 			slice,
 	  }: SliceComponentProps<TSlice, TContext>): JSX.Element | null => {
+			const type = "slice_type" in slice ? slice.slice_type : slice.type;
+
 			React.useEffect(() => {
 				console.warn(
-					`[SliceZone] Could not find a component for Slice type "${slice.slice_type}"`,
+					`[SliceZone] Could not find a component for Slice type "${type}"`,
 					slice,
 				);
-			}, [slice]);
+			}, [slice, type]);
 
 			return (
-				<section
-					data-slice-zone-todo-component=""
-					data-slice-type={slice.slice_type}
-				>
-					Could not find a component for Slice type &ldquo;{slice.slice_type}
+				<section data-slice-zone-todo-component="" data-slice-type={type}>
+					Could not find a component for Slice type &ldquo;{type}
 					&rdquo;
 				</section>
 			);
@@ -149,7 +178,7 @@ type SliceZoneResolverArgs<TSlice extends SliceLike = SliceLike> = {
 	/**
 	 * The name of the Slice.
 	 */
-	sliceName: PascalCase<TSlice["slice_type"]>;
+	sliceName: PascalCase<ExtractSliceType<TSlice>>;
 
 	/**
 	 * The index of the Slice in the Slice Zone.
@@ -243,14 +272,16 @@ export const SliceZone = <TSlice extends SliceLike, TContext>({
 }: SliceZoneProps<TSlice, TContext>): JSX.Element => {
 	const renderedSlices = React.useMemo(() => {
 		return slices.map((slice, index) => {
-			let Comp = (components[slice.slice_type as keyof typeof components] ||
+			const type = "slice_type" in slice ? slice.slice_type : slice.type;
+
+			let Comp = (components[type as keyof typeof components] ||
 				defaultComponent) as SliceComponentType<TSlice, TContext>;
 
 			// TODO: Remove `resolver` in v3 in favor of `components`.
 			if (resolver) {
 				const resolvedComp = resolver({
 					slice,
-					sliceName: pascalCase(slice.slice_type),
+					sliceName: pascalCase(type),
 					i: index,
 				});
 

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}`;
+};

package/src/lib/pascalCase.ts

@@ -34,7 +34,7 @@ type InnerCamelCaseStringArray<
 
 type CamelCaseStringArray<Parts extends readonly string[]> = Parts extends [
 	`${infer FirstPart}`,
-	...infer RemainingParts
+	...infer RemainingParts,
 ]
 	? Uncapitalize<`${FirstPart}${InnerCamelCaseStringArray<
 			RemainingParts,