fix: warn when passing className to <PrismicRichText> or <PrismicText>

messages/classname-is-not-a-valid-prop.md

@@ -0,0 +1,30 @@
+# `className` is not a valid prop
+
+`<PrismicRichText>` and `<PrismicText>` do not accept a `className` prop. These components render an array of React components and do not have a wrapping element.
+
+To add a `className` as a wrapper around the output of `<PrismicRichText>` or `<PrismicText>`, add a wrapper element with the `className`.
+
+```tsx
+// ✅ Correct
+<div className="prose">
+	<PrismicRichText field={doc.data.richTextField} />
+</div>
+```
+
+```tsx
+// ❌ Incorrect
+<PrismicRichText field={doc.data.richTextField} className="prose" />
+```
+
+To add a `className` to a specific block type when using `<PrismicRichText>`, provide a custom component.
+
+```tsx
+<PrismicRichText
+	field={doc.data.richTextField}
+	components={{
+		heading1: ({ children }) => (
+			<h1 className="font-bold text-3xl">{children}</h1>
+		),
+	}}
+/>
+```

src/PrismicText.tsx

@@ -1,7 +1,6 @@
 import * as React from "react";
 import * as prismic from "@prismicio/client";
 
-import { __PRODUCTION__ } from "./lib/__PRODUCTION__";
 import { devMsg } from "./lib/devMsg";
 
 /**
@@ -45,7 +44,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 (process.env.NODE_ENV === "development") {
+		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(
+					"classname-is-not-a-valid-prop",
+				)}.`,
+				props.field,
+			);
+		}
+
 		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(

src/react-server/PrismicRichText.tsx

@@ -4,6 +4,7 @@
 
 import { JSXFunctionSerializer, JSXMapSerializer } from "../types";
 import { LinkProps, PrismicLink } from "./PrismicLink";
+import { devMsg } from "../lib/devMsg";
 
 /**
  * Props for `<PrismicRichText>`.
@@ -222,8 +223,20 @@
 	components,
 	externalLinkComponent,
 	internalLinkComponent,
+	...restProps
 }: PrismicRichTextProps<LinkResolverFunction>): JSX.Element | null {
 	return React.useMemo(() => {
+		if (process.env.NODE_ENV === "development") {
+			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 (prismic.isFilled.richText(field)) {
 			const serializer = prismicR.composeSerializers(
 				typeof components === "object"
@@ -256,7 +269,7 @@
 		} else {
 			return fallback != null ? <>{fallback}</> : null;
 		}
 	}, [
 		field,
 		internalLinkComponent,
 		externalLinkComponent,

test/PrismicText.test.tsx

@@ -1,14 +1,14 @@
 import { it, expect, vi } from "vitest";
-import * as prismicT from "@prismicio/types";
+import * as prismic from "@prismicio/client";
 
 import { PrismicText } from "../src";
 
 import { renderJSON } from "./__testutils__/renderJSON";
 
 it("returns string when passed RichTextField", () => {
-	const field: prismicT.RichTextField = [
+	const field: prismic.RichTextField = [
 		{
-			type: prismicT.RichTextNodeType.heading1,
+			type: prismic.RichTextNodeType.heading1,
 			text: "Heading 1",
 			spans: [],
 		},
@@ -54,6 +54,10 @@ it("returns fallback when passed empty field", () => {
 });
 
 it("throws error if passed a string-based field (e.g. Key Text or Select)", () => {
+	// The error is only thrown  in "development".
+	const originalNodeEnv = process.env.NODE_ENV;
+	process.env.NODE_ENV = "development";
+
 	// Used to supress logging the error in this it.
 	const consoleErrorStub = vi
 		.spyOn(console, "error")
@@ -69,4 +73,33 @@ it("throws error if passed a string-based field (e.g. Key Text or Select)", () =
 	}).throws(/prismictext-works-only-with-rich-text-and-title-fields/);
 
 	consoleErrorStub.mockRestore();
+	process.env.NODE_ENV = originalNodeEnv;
+});
+
+it("warns if a className prop is provided", async () => {
+	const field: prismic.RichTextField = [];
+
+	// The warning only logs in "development".
+	const originalNodeEnv = process.env.NODE_ENV;
+	process.env.NODE_ENV = "development";
+
+	const consoleWarnSpy = vi
+		.spyOn(console, "warn")
+		.mockImplementation(() => void 0);
+
+	renderJSON(
+		<PrismicText
+			field={field}
+			// @ts-expect-error - We are purposely passing an invalid prop to trigger the console wraning.
+			className="foo"
+		/>,
+	);
+
+	expect(consoleWarnSpy).toHaveBeenCalledWith(
+		expect.stringMatching(/classname-is-not-a-valid-prop/),
+		field,
+	);
+
+	consoleWarnSpy.mockRestore();
+	process.env.NODE_ENV = originalNodeEnv;
 });