@prismicio/react 2.9.1 → 3.0.0-alpha.0

package/src/PrismicRichText.tsx

@@ -1,38 +1,338 @@
-"use client";
+import {
+	cloneElement,
+	ComponentType,
+	Fragment,
+	isValidElement,
+	ReactNode,
+} from "react";
+import {
+	isFilled,
+	LinkResolverFunction,
+	RichTextField,
+	RTAnyNode,
+} from "@prismicio/client";
+import {
+	composeSerializers,
+	serialize,
+	wrapMapSerializer,
+	RichTextFunctionSerializer,
+	RichTextMapSerializer,
+} from "@prismicio/client/richtext";
+import { DEV } from "esm-env";
 
-import * as prismic from "@prismicio/client";
-import * as prismicR from "@prismicio/richtext";
+import { devMsg } from "./lib/devMsg.js";
 
-import {
-	PrismicRichText as ServerPrismicRichText,
-	PrismicRichTextProps,
-} from "./react-server/PrismicRichText";
-
-import { usePrismicContext } from "./usePrismicContext";
-
-export type { PrismicRichTextProps };
-
-export const PrismicRichText = function PrismicRichText<
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	LinkResolverFunction extends prismic.LinkResolverFunction<any> = prismic.LinkResolverFunction,
->({ components, ...restProps }: PrismicRichTextProps<LinkResolverFunction>) {
-	const context = usePrismicContext();
-
-	const serializer = prismicR.composeSerializers(
-		typeof components === "object"
-			? prismicR.wrapMapSerializer(components)
-			: components,
-		typeof context.richTextComponents === "object"
-			? prismicR.wrapMapSerializer(context.richTextComponents)
-			: context.richTextComponents,
+import { LinkProps, PrismicLink } from "./PrismicLink.js";
+
+/**
+ * A function mapping Rich Text block types to React 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/technologies/templating-rich-text-and-title-fields-javascript}
+ */
+export type JSXFunctionSerializer = RichTextFunctionSerializer<ReactNode>;
+
+/**
+ * A map of Rich Text block types to React 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/technologies/templating-rich-text-and-title-fields-javascript}
+ */
+export type JSXMapSerializer = RichTextMapSerializer<ReactNode>;
+
+/** Props for `<PrismicRichText>`. */
+export type PrismicRichTextProps = {
+	/** The Prismic Rich Text field to render. */
+	field: RichTextField | null | undefined;
+
+	/**
+	 * The Link Resolver used to resolve links.
+	 *
+	 * @remarks
+	 * If your app uses Route Resolvers when querying for your Prismic
+	 * repository's content, a Link Resolver does not need to be provided.
+	 *
+	 * @see Learn about Link Resolvers and Route Resolvers {@link https://io/docs/core-concepts/link-resolver-route-resolver}
+	 */
+	linkResolver?: LinkResolverFunction;
+
+	/**
+	 * A map or function that maps a Rich Text block to a React component.
+	 *
+	 * @remarks
+	 * Prefer using a map serializer over the function serializer when possible.
+	 * The map serializer is simpler to maintain.
+	 *
+	 * @example A map serializer.
+	 *
+	 * ```jsx
+	 * {
+	 *   heading1: ({children}) => <Heading>{children}</Heading>
+	 * }
+	 * ```
+	 *
+	 * @example A function serializer.
+	 *
+	 * ```jsx
+	 * (type, node, content, children) => {
+	 * 	switch (type) {
+	 * 		case "heading1": {
+	 * 			return <Heading>{children}</Heading>;
+	 * 		}
+	 * 	}
+	 * };
+	 * ```
+	 */
+	components?: JSXMapSerializer | JSXFunctionSerializer;
+
+	/**
+	 * The React component rendered for links when the URL is internal.
+	 *
+	 * @defaultValue `<a>`
+	 */
+	internalLinkComponent?: ComponentType<LinkProps>;
+
+	/**
+	 * The React component rendered for links when the URL is external.
+	 *
+	 * @defaultValue `<a>`
+	 */
+	externalLinkComponent?: ComponentType<LinkProps>;
+
+	/**
+	 * The value to be rendered when the field is empty. If a fallback is not
+	 * given, `null` will be rendered.
+	 */
+	fallback?: ReactNode;
+};
+
+type CreateDefaultSerializerArgs = {
+	linkResolver: LinkResolverFunction | undefined;
+	internalLinkComponent?: ComponentType<LinkProps>;
+	externalLinkComponent?: ComponentType<LinkProps>;
+};
+
+const getDir = (node: RTAnyNode): "rtl" | undefined => {
+	if ("direction" in node && node.direction === "rtl") {
+		return "rtl";
+	}
+};
+
+const createDefaultSerializer = (
+	args: CreateDefaultSerializerArgs,
+): JSXFunctionSerializer =>
+	wrapMapSerializer<ReactNode>({
+		heading1: ({ node, children, key }) => (
+			<h1 key={key} dir={getDir(node)}>
+				{children}
+			</h1>
+		),
+		heading2: ({ node, children, key }) => (
+			<h2 key={key} dir={getDir(node)}>
+				{children}
+			</h2>
+		),
+		heading3: ({ node, children, key }) => (
+			<h3 key={key} dir={getDir(node)}>
+				{children}
+			</h3>
+		),
+		heading4: ({ node, children, key }) => (
+			<h4 key={key} dir={getDir(node)}>
+				{children}
+			</h4>
+		),
+		heading5: ({ node, children, key }) => (
+			<h5 key={key} dir={getDir(node)}>
+				{children}
+			</h5>
+		),
+		heading6: ({ node, children, key }) => (
+			<h6 key={key} dir={getDir(node)}>
+				{children}
+			</h6>
+		),
+		paragraph: ({ node, children, key }) => (
+			<p key={key} dir={getDir(node)}>
+				{children}
+			</p>
+		),
+		preformatted: ({ node, key }) => <pre key={key}>{node.text}</pre>,
+		strong: ({ children, key }) => <strong key={key}>{children}</strong>,
+		em: ({ children, key }) => <em key={key}>{children}</em>,
+		listItem: ({ node, children, key }) => (
+			<li key={key} dir={getDir(node)}>
+				{children}
+			</li>
+		),
+		oListItem: ({ node, children, key }) => (
+			<li key={key} dir={getDir(node)}>
+				{children}
+			</li>
+		),
+		list: ({ children, key }) => <ul key={key}>{children}</ul>,
+		oList: ({ children, key }) => <ol key={key}>{children}</ol>,
+		image: ({ node, key }) => {
+			const img = (
+				<img
+					src={node.url}
+					alt={node.alt ?? undefined}
+					data-copyright={node.copyright ? node.copyright : undefined}
+				/>
+			);
+
+			return (
+				<p key={key} className="block-img">
+					{node.linkTo ? (
+						<PrismicLink
+							linkResolver={args.linkResolver}
+							internalComponent={args.internalLinkComponent}
+							externalComponent={args.externalLinkComponent}
+							field={node.linkTo}
+						>
+							{img}
+						</PrismicLink>
+					) : (
+						img
+					)}
+				</p>
+			);
+		},
+		embed: ({ node, key }) => (
+			<div
+				key={key}
+				data-oembed={node.oembed.embed_url}
+				data-oembed-type={node.oembed.type}
+				data-oembed-provider={node.oembed.provider_name}
+				dangerouslySetInnerHTML={{ __html: node.oembed.html ?? "" }}
+			/>
+		),
+		hyperlink: ({ node, children, key }) => (
+			<PrismicLink
+				key={key}
+				field={node.data}
+				linkResolver={args.linkResolver}
+				internalComponent={args.internalLinkComponent}
+				externalComponent={args.externalLinkComponent}
+			>
+				{children}
+			</PrismicLink>
+		),
+		label: ({ node, children, key }) => (
+			<span key={key} className={node.data.label}>
+				{children}
+			</span>
+		),
+		span: ({ text, key }) => {
+			const result: ReactNode[] = [];
+
+			let i = 0;
+			for (const line of text.split("\n")) {
+				if (i > 0) {
+					result.push(<br key={`${i}__break`} />);
+				}
+
+				result.push(<Fragment key={`${i}__line`}>{line}</Fragment>);
+
+				i++;
+			}
+
+			return <Fragment key={key}>{result}</Fragment>;
+		},
+	});
+
+/**
+ * React component that renders content from a Prismic Rich Text field. By
+ * default, HTML elements are rendered for each piece of content. A `heading1`
+ * block will render an `<h1>` HTML element, for example. Links will use
+ * `<PrismicLink>` by default which can be customized using the
+ * `internalLinkComponent` and `externalLinkComponent` props.
+ *
+ * To customize the components that are rendered, provide a map or function
+ * serializer to the `components` prop.
+ *
+ * @remarks
+ * This component returns a React fragment with no wrapping element around the
+ * content. If you need a wrapper, add a component around `<PrismicRichText>`.
+ *
+ * @example Rendering a Rich Text field using the default HTMl elements.
+ *
+ * ```jsx
+ * <PrismicRichText field={document.data.content} />;
+ * ```
+ *
+ * @example Rendering a Rich Text field using a custom set of React components.
+ *
+ * ```jsx
+ * <PrismicRichText
+ * 	field={document.data.content}
+ * 	components={{
+ * 		heading1: ({ children }) => <Heading>{children}</Heading>,
+ * 	}}
+ * />;
+ * ```
+ *
+ * @param props - Props for the component.
+ *
+ * @returns The Rich Text field's content as React components.
+ *
+ * @see Learn about Rich Text fields {@link https://io/docs/core-concepts/rich-text-title}
+ * @see Learn about Rich Text serializers {@link https://io/docs/core-concepts/html-serializer}
+ */
+export function PrismicRichText(props: PrismicRichTextProps) {
+	const {
+		linkResolver,
+		field,
+		fallback,
+		components,
+		externalLinkComponent,
+		internalLinkComponent,
+		...restProps
+	} = props;
+
+	if (DEV) {
+		if ("className" in restProps) {
+			console.warn(
+				`[PrismicRichText] className cannot be passed to <PrismicRichText> since it renders an array without a wrapping component. For more details, see ${devMsg(
+					"classname-is-not-a-valid-prop",
+				)}.`,
+				field,
+			);
+		}
+	}
+
+	if (!isFilled.richText(field)) {
+		return fallback != null ? <>{fallback}</> : null;
+	}
+
+	const serializer = composeSerializers<ReactNode>(
+		typeof components === "object" ? wrapMapSerializer(components) : components,
+		createDefaultSerializer({
+			linkResolver,
+			internalLinkComponent,
+			externalLinkComponent,
+		}),
 	);
 
-	return (
-		<ServerPrismicRichText
-			components={serializer}
-			internalLinkComponent={context.internalLinkComponent}
-			externalLinkComponent={context.externalLinkComponent}
-			{...restProps}
-		/>
+	// The serializer is wrapped in a higher-order function that
+	// automatically applies a key to React Elements if one is not already
+	// given.
+	const serialized = serialize<ReactNode>(
+		field,
+		(type, node, text, children, key) => {
+			const result = serializer(type, node, text, children, key);
+
+			if (isValidElement(result) && result.key == null) {
+				return cloneElement(result, { key });
+			} else {
+				return result;
+			}
+		},
 	);
-};
+
+	if (!serialized) {
+		return fallback != null ? <>{fallback}</> : null;
+	}
+
+	return <>{serialized}</>;
+}

package/src/PrismicText.tsx

@@ -1,16 +1,12 @@
-import * as React from "react";
-import * as prismic from "@prismicio/client";
+import { asText, isFilled, RichTextField } from "@prismicio/client";
+import { DEV } from "esm-env";
 
-import { devMsg } from "./lib/devMsg";
+import { devMsg } from "./lib/devMsg.js";
 
-/**
- * Props for `<PrismicText>`.
- */
+/** Props for `<PrismicText>`. */
 export type PrismicTextProps = {
-	/**
-	 * The Prismic Rich Text field to render.
-	 */
-	field: prismic.RichTextField | null | undefined;
+	/** The Prismic Rich Text field to render. */
+	field: RichTextField | null | undefined;
 
 	/**
 	 * The string rendered when the field is empty. If a fallback is not given,
@@ -18,9 +14,7 @@ export type PrismicTextProps = {
 	 */
 	fallback?: string;
 
-	/**
-	 * The separator used between blocks. Defaults to `\n`.
-	 */
+	/** The separator used between blocks. Defaults to `\n`. */
 	separator?: string;
 };
 
@@ -31,6 +25,7 @@ export type PrismicTextProps = {
  * @remarks
  * This component returns a React fragment with no wrapping element around the
  * content. If you need a wrapper, add a component around `<PrismicText>`.
+ *
  * @example Rendering a Rich Text field as plain text.
  *
  * ```jsx
@@ -41,13 +36,12 @@ export type PrismicTextProps = {
  *
  * @returns The Rich Text field's content as plain text.
  *
- * @see Learn about Rich Text fields {@link https://prismic.io/docs/core-concepts/rich-text-title}
+ * @see Learn about Rich Text fields {@link https://io/docs/core-concepts/rich-text-title}
  */
-export const PrismicText = (props: PrismicTextProps): JSX.Element | null => {
-	if (
-		typeof process !== "undefined" &&
-		process.env.NODE_ENV === "development"
-	) {
+export function PrismicText(props: PrismicTextProps) {
+	const { field, fallback, separator } = props;
+
+	if (DEV) {
 		if ("className" in props) {
 			console.warn(
 				`[PrismicText] className cannot be passed to <PrismicText> since it renders plain text without a wrapping component. For more details, see ${devMsg(
@@ -56,23 +50,24 @@ export const PrismicText = (props: PrismicTextProps): JSX.Element | null => {
 				props.field,
 			);
 		}
+	}
 
-		if (typeof props.field === "string") {
-			throw new Error(
+	if (typeof props.field === "string") {
+		if (DEV) {
+			console.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",
 				)}`,
+				props.field,
 			);
 		}
+
+		return null;
 	}
 
-	return React.useMemo(() => {
-		if (prismic.isFilled.richText(props.field)) {
-			const text = prismic.asText(props.field, props.separator);
+	if (!isFilled.richText(field)) {
+		return fallback != null ? <>{fallback}</> : null;
+	}
 
-			return <>{text}</>;
-		} else {
-			return props.fallback != null ? <>{props.fallback}</> : null;
-		}
-	}, [props.field, props.fallback, props.separator]);
-};
+	return <>{asText(field, { separator })}</>;
+}

package/src/PrismicToolbar.tsx

@@ -1,38 +1,27 @@
 "use client";
 
-import * as React from "react";
+import { useEffect } from "react";
 import { getToolbarSrc } from "@prismicio/client";
 
-/**
- * Props for `<PrismicToolbar>`.
- */
+/** Props for `<PrismicToolbar>`. */
 export type PrismicToolbarProps = {
 	/**
 	 * The name of the Prismic repository. For example, `"my-repo"` if the
 	 * repository URL is `my-repo.prismic.io`.
 	 */
 	repositoryName: string;
-
-	/**
-	 * The type of toolbar needed for the repository. Defaults to `"new"`.
-	 *
-	 * @deprecated All repositories use the "new"-type toolbar. This option can be
-	 *   removed.
-	 * @see To check which version you need, view the Prismic Toolbar documentation {@link https://prismic.io/docs/technologies/previews-and-the-prismic-toolbar-reactjs}
-	 */
-	type?: "new" | "legacy";
 };
 
 /**
  * React component that injects the Prismic Toolbar into the app. This component
  * can be placed anywhere in the React tree.
  */
-export const PrismicToolbar = ({
-	repositoryName,
-}: PrismicToolbarProps): null => {
+export function PrismicToolbar(props: PrismicToolbarProps) {
+	const { repositoryName } = props;
+
 	const src = getToolbarSrc(repositoryName);
 
-	React.useEffect(() => {
+	useEffect(() => {
 		const existingScript = document.querySelector(`script[src="${src}"]`);
 
 		if (!existingScript) {
@@ -44,22 +33,13 @@ export const PrismicToolbar = ({
 			script.dataset.prismicToolbar = "";
 			script.dataset.repositoryName = repositoryName;
 
-			// 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 (typeof process !== "undefined" && process.env.NODE_ENV === "test") {
-				// @ts-expect-error - `_evaluateScript` is a Happy DOM-specific property.
-				script._evaluateScript = false;
-			}
+			// Disable Happy DOM `<script>` evaluation during tests.
+			// @ts-expect-error - `_evaluateScript` is a Happy DOM-specific property.
+			script._evaluateScript = false;
 
 			document.body.appendChild(script);
 		}
 	}, [repositoryName, src]);
 
 	return null;
-};
+}