@prismicio/react 2.9.0 → 3.0.0-alpha.0

package/package.json

@@ -1,113 +1,96 @@
 {
 	"name": "@prismicio/react",
-	"version": "2.9.0",
+	"version": "3.0.0-alpha.0",
 	"description": "React components and hooks to fetch and present Prismic content",
 	"keywords": [
 		"typescript",
 		"prismic",
-		"react",
-		"cms",
-		"hook"
+		"react"
 	],
 	"repository": {
 		"type": "git",
-		"url": "ssh://git@github.com/prismicio/prismic-react.git"
+		"url": "git+https://github.com/prismicio/prismic-react.git"
 	},
 	"license": "Apache-2.0",
 	"author": "Prismic <contact@prismic.io> (https://prismic.io)",
 	"sideEffects": false,
+	"type": "module",
 	"exports": {
 		".": {
-			"react-server": {
-				"require": {
-					"types": "./dist/react-server/index.d.ts",
-					"default": "./dist/react-server.cjs"
-				},
-				"import": {
-					"types": "./dist/react-server/index.d.ts",
-					"default": "./dist/react-server.js"
-				}
-			},
-			"default": {
-				"require": {
-					"types": "./dist/index.d.ts",
-					"default": "./dist/index.cjs"
-				},
-				"import": {
-					"types": "./dist/index.d.ts",
-					"default": "./dist/index.js"
-				}
-			}
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
 		},
 		"./package.json": "./package.json"
 	},
-	"main": "./dist/index.cjs",
-	"module": "./dist/index.js",
-	"react-native": "./dist/index.js",
-	"types": "./dist/index.d.ts",
+	"typesVersions": {
+		"*": {
+			"*": [
+				"./dist/index.d.ts"
+			]
+		}
+	},
 	"files": [
 		"dist",
 		"src"
 	],
+	"workspaces": [
+		".",
+		"e2e-projects/*"
+	],
 	"scripts": {
 		"build": "vite build",
 		"dev": "vite build --watch",
+		"e2e": "playwright test",
+		"e2e:ui": "npm run e2e -- --ui",
 		"format": "prettier --write .",
-		"lint": "eslint --ext .js,.jsx,.ts,.tsx .",
-		"types": "tsc --noEmit",
+		"lint": "eslint",
 		"prepare": "npm run build",
 		"release": "npm run build && npm run test && standard-version && git push --follow-tags && npm run build && npm publish",
-		"release:alpha": "npm run build && npm run test && standard-version --release-as minor --prerelease alpha && git push --follow-tags && npm run build && npm publish --tag alpha",
-		"release:alpha:dry": "standard-version --release-as minor --prerelease alpha --dry-run",
+		"release:alpha": "npm run build && npm run test && standard-version --release-as major --prerelease alpha && git push --follow-tags && npm run build && npm publish --tag alpha",
+		"release:alpha:dry": "standard-version --release-as major --prerelease alpha --dry-run",
 		"release:dry": "standard-version --dry-run",
-		"unit": "vitest run --coverage",
-		"unit:watch": "vitest watch",
 		"size": "size-limit",
-		"test": "npm run lint && npm run types && npm run unit && npm run build && npm run size"
+		"test": "npm run lint && npm run types && npm run build && npm run e2e && npm run size && npm run e2e",
+		"types": "tsc --noEmit"
 	},
 	"dependencies": {
-		"@prismicio/richtext": "^2.1.5"
+		"esm-env": "^1.2.2"
 	},
 	"devDependencies": {
-		"@prismicio/client": "^7.11.0",
-		"@prismicio/mock": "0.4.0",
-		"@size-limit/preset-small-lib": "^8.2.4",
-		"@testing-library/react": "^14.0.0",
-		"@types/node-fetch": "^3.0.3",
-		"@types/react": "^18.2.9",
-		"@types/react-test-renderer": "^18.0.0",
-		"@typescript-eslint/eslint-plugin": "^5.59.9",
-		"@typescript-eslint/parser": "^5.59.9",
-		"@vitejs/plugin-react": "^4.0.0",
-		"@vitest/coverage-v8": "^0.32.0",
-		"eslint": "^8.42.0",
-		"eslint-config-prettier": "^8.8.0",
-		"eslint-plugin-prettier": "^4.2.1",
-		"eslint-plugin-react": "^7.32.2",
-		"eslint-plugin-react-hooks": "^4.6.0",
-		"eslint-plugin-tsdoc": "^0.2.17",
-		"happy-dom": "^9.20.3",
-		"msw": "^1.2.1",
-		"node-fetch": "^3.3.1",
-		"prettier": "^2.8.8",
-		"prettier-plugin-jsdoc": "^0.4.2",
-		"react": "^18.2.0",
-		"react-dom": "^18.2.0",
-		"react-test-renderer": "^18.2.0",
-		"rollup-plugin-preserve-directives": "^0.2.0",
-		"size-limit": "^8.2.4",
+		"@eslint/js": "^9.18.0",
+		"@playwright/test": "^1.49.1",
+		"@prismicio/client": "^7.12.0",
+		"@rollup/plugin-typescript": "^12.1.2",
+		"@size-limit/preset-small-lib": "^11.1.6",
+		"@types/react": "^19.0.7",
+		"@types/react-dom": "^19.0.3",
+		"@vitejs/plugin-react": "^4.3.4",
+		"dotenv": "^16.4.7",
+		"eslint": "^9.18.0",
+		"eslint-config-prettier": "^10.0.1",
+		"eslint-plugin-prettier": "^5.2.2",
+		"eslint-plugin-react": "^7.37.4",
+		"eslint-plugin-react-hooks": "^5.1.0",
+		"eslint-plugin-tsdoc": "^0.4.0",
+		"playwright": "^1.49.1",
+		"prettier": "^3.4.2",
+		"prettier-plugin-jsdoc": "^1.3.2",
+		"react": "^19.0.0",
+		"react-dom": "^19.0.0",
+		"rollup-plugin-preserve-directives": "^0.4.0",
+		"rollup-preserve-directives": "^1.1.3",
+		"size-limit": "^11.1.6",
 		"standard-version": "^9.5.0",
-		"typescript": "^5.0.4",
-		"vite": "^4.3.9",
-		"vite-plugin-sdk": "^0.1.1",
-		"vitest": "^0.32.0"
+		"typescript": "^5.7.3",
+		"typescript-eslint": "^8.20.0",
+		"vite": "^6.0.7"
 	},
 	"peerDependencies": {
-		"@prismicio/client": "^6 || ^7",
+		"@prismicio/client": "^7",
 		"react": "^18 || ^19.0.0-rc.0"
 	},
 	"engines": {
-		"node": ">=12.7.0"
+		"node": ">=18"
 	},
 	"publishConfig": {
 		"access": "public"

package/src/PrismicImage.tsx

@@ -1,23 +1,36 @@
-import * as React from "react";
-import * as prismic from "@prismicio/client";
-import { ImgixURLParams } from "imgix-url-builder";
+import {
+	ForwardedRef,
+	forwardRef,
+	type ComponentProps,
+	FC,
+	ReactNode,
+} from "react";
+import {
+	type ImageFieldImage,
+	asImagePixelDensitySrcSet,
+	asImageWidthSrcSet,
+	isFilled,
+} from "@prismicio/client";
+import { DEV } from "esm-env";
 
-import { devMsg } from "./lib/devMsg";
+import { devMsg } from "./lib/devMsg.js";
 
-/**
- * Props for `<PrismicImage>`.
- */
+type ImgixURLParams = Omit<
+	NonNullable<Parameters<typeof asImageWidthSrcSet>[1]>,
+	"widths"
+> &
+	Omit<
+		NonNullable<Parameters<typeof asImagePixelDensitySrcSet>[1]>,
+		"pixelDensities"
+	>;
+
+/** Props for `<PrismicImage>`. */
 export type PrismicImageProps = Omit<
-	React.DetailedHTMLProps<
-		React.ImgHTMLAttributes<HTMLImageElement>,
-		HTMLImageElement
-	>,
+	ComponentProps<"img">,
 	"src" | "srcset" | "alt"
 > & {
-	/**
-	 * The Prismic Image field or thumbnail to render.
-	 */
-	field: prismic.ImageFieldImage | null | undefined;
+	/** The Prismic Image field or thumbnail to render. */
+	field: ImageFieldImage | null | undefined;
 
 	/**
 	 * An object of Imgix URL API parameters to transform the image.
@@ -42,6 +55,12 @@ export type PrismicImageProps = Omit<
 	 * https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/alt#decorative_images
 	 */
 	fallbackAlt?: "";
+
+	/**
+	 * The value to be rendered when the field is empty. If a fallback is not
+	 * given, `null` will be rendered.
+	 */
+	fallback?: ReactNode;
 } & (
 		| {
 				/**
@@ -56,19 +75,13 @@ export type PrismicImageProps = Omit<
 				 * `"thumbnails"` as the `widths` prop.
 				 */
 				widths?:
-					| NonNullable<
-							Parameters<typeof prismic.asImageWidthSrcSet>[1]
-					  >["widths"]
+					| NonNullable<Parameters<typeof asImageWidthSrcSet>[1]>["widths"]
 					| "defaults";
-				/**
-				 * Not used when the `widths` prop is used.
-				 */
+				/** Not used when the `widths` prop is used. */
 				pixelDensities?: never;
 		  }
 		| {
-				/**
-				 * Not used when the `widths` prop is used.
-				 */
+				/** Not used when the `widths` prop is used. */
 				widths?: never;
 				/**
 				 * Pixel densities used to build a `srcset` value for the Image field.
@@ -78,7 +91,7 @@ export type PrismicImageProps = Omit<
 				 */
 				pixelDensities:
 					| NonNullable<
-							Parameters<typeof prismic.asImagePixelDensitySrcSet>[1]
+							Parameters<typeof asImagePixelDensitySrcSet>[1]
 					  >["pixelDensities"]
 					| "defaults";
 		  }
@@ -103,46 +116,50 @@ export type PrismicImageProps = Omit<
  *
  * @returns A responsive image component for the given Image field.
  */
-export const PrismicImage = React.forwardRef(function PrismicImage(
-	{
-		field,
-		alt,
-		fallbackAlt,
-		imgixParams = {},
-		widths,
-		pixelDensities,
-		...restProps
-	}: PrismicImageProps,
-	ref: React.ForwardedRef<HTMLImageElement>,
-): JSX.Element | null {
-	if (
-		typeof process !== "undefined" &&
-		process.env.NODE_ENV === "development"
+export const PrismicImage: FC<PrismicImageProps> = forwardRef(
+	function PrismicImage(
+		props: PrismicImageProps,
+		ref: ForwardedRef<HTMLImageElement>,
 	) {
-		if (typeof alt === "string" && 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",
-				)}`,
-			);
-		}
+		const {
+			field,
+			alt,
+			fallbackAlt,
+			imgixParams = {},
+			widths,
+			pixelDensities,
+			fallback,
+			...restProps
+		} = props;
 
-		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 (DEV) {
+			if (typeof alt === "string" && 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 (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 (!isFilled.imageThumbnail(field)) {
+			return <>{fallback}</>;
 		}
-	}
 
-	if (prismic.isFilled.imageThumbnail(field)) {
 		const resolvedImgixParams = imgixParams;
 		for (const x in imgixParams) {
 			if (resolvedImgixParams[x as keyof typeof resolvedImgixParams] === null) {
@@ -154,7 +171,7 @@ export const PrismicImage = React.forwardRef(function PrismicImage(
 		let srcSet: string | undefined;
 
 		if (widths || !pixelDensities) {
-			const res = prismic.asImageWidthSrcSet(field, {
+			const res = asImageWidthSrcSet(field, {
 				...resolvedImgixParams,
 				widths: widths === "defaults" ? undefined : widths,
 			} as ImgixURLParams);
@@ -162,7 +179,7 @@ export const PrismicImage = React.forwardRef(function PrismicImage(
 			src = res.src;
 			srcSet = res.srcset;
 		} else if (pixelDensities) {
-			const res = prismic.asImagePixelDensitySrcSet(field, {
+			const res = asImagePixelDensitySrcSet(field, {
 				...resolvedImgixParams,
 				pixelDensities:
 					pixelDensities === "defaults" ? undefined : pixelDensities,
@@ -181,7 +198,5 @@ export const PrismicImage = React.forwardRef(function PrismicImage(
 				{...restProps}
 			/>
 		);
-	} else {
-		return null;
-	}
-});
+	},
+);

package/src/PrismicLink.tsx

@@ -1,41 +1,211 @@
-"use client";
+import {
+	ComponentProps,
+	ComponentType,
+	ElementType,
+	ForwardedRef,
+	HTMLAttributeAnchorTarget,
+	ReactNode,
+	forwardRef,
+} from "react";
+import {
+	type LinkField,
+	type LinkResolverFunction,
+	type PrismicDocument,
+	asLinkAttrs,
+	type AsLinkAttrsConfig,
+} from "@prismicio/client";
+import { DEV } from "esm-env";
 
-import * as React from "react";
+import { devMsg } from "./lib/devMsg.js";
 
-import {
-	PrismicLink as ServerPrismicLink,
-	LinkProps,
-	PrismicLinkProps,
-	defaultComponent,
-} from "./react-server/PrismicLink";
+/** The default component rendered for internal and external links. */
+const defaultComponent = "a";
+
+/** Props provided to a component when rendered with `<PrismicLink>`. */
+export interface LinkProps {
+	/** The URL to link. */
+	href: string;
+
+	/**
+	 * The `target` attribute for anchor elements. If the Prismic field is
+	 * configured to open in a new window, this prop defaults to `_blank`.
+	 */
+	target?: HTMLAttributeAnchorTarget;
+
+	/**
+	 * The `rel` attribute for anchor elements. If the `target` prop is set to
+	 * `"_blank"`, this prop defaults to `"noopener noreferrer"`.
+	 */
+	rel?: string;
+
+	/** Children for the component. * */
+	children?: ReactNode;
+}
+
+export type PrismicLinkProps<
+	InternalComponentProps = ComponentProps<typeof defaultComponent>,
+	ExternalComponentProps = ComponentProps<typeof defaultComponent>,
+> = Omit<
+	InternalComponentProps & ExternalComponentProps,
+	"rel" | "href" | "children"
+> & {
+	/**
+	 * The `rel` attribute for the link. By default, `"noreferrer"` is provided if
+	 * the link's URL is external. This prop can be provided a function to use the
+	 * link's metadata to determine the `rel` value.
+	 */
+	rel?: string | AsLinkAttrsConfig["rel"];
+
+	/**
+	 * 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://prismic.io/docs/core-concepts/link-resolver-route-resolver}
+	 */
+	linkResolver?: LinkResolverFunction;
 
-import { usePrismicContext } from "./usePrismicContext";
+	/**
+	 * The component rendered for internal URLs. Defaults to `<a>`.
+	 *
+	 * If your app uses a client-side router that requires a special Link
+	 * component, provide the Link component to this prop.
+	 */
+	internalComponent?: ElementType<InternalComponentProps>;
 
-export type { LinkProps, PrismicLinkProps };
+	/** The component rendered for external URLs. Defaults to `<a>`. */
+	externalComponent?: ComponentType<ExternalComponentProps>;
 
-export const PrismicLink = React.forwardRef(function PrismicLink<
-	InternalComponentProps = React.ComponentProps<typeof defaultComponent>,
-	ExternalComponentProps = React.ComponentProps<typeof defaultComponent>,
+	/**
+	 * The children to render for the link. If no children are provided, the
+	 * link's `text` property will be used.
+	 */
+	children?: ReactNode;
+} & (
+		| {
+				document: PrismicDocument | null | undefined;
+				href?: never;
+				field?: never;
+		  }
+		| {
+				field: LinkField | null | undefined;
+				href?: never;
+				document?: never;
+		  }
+		| {
+				href: LinkProps["href"];
+				field?: LinkField | null | undefined;
+				document?: never;
+		  }
+	);
+
+export const PrismicLink = forwardRef(function PrismicLink<
+	InternalComponentProps = ComponentProps<typeof defaultComponent>,
+	ExternalComponentProps = ComponentProps<typeof defaultComponent>,
 >(
 	props: PrismicLinkProps<InternalComponentProps, ExternalComponentProps>,
-	ref: React.ForwardedRef<Element>,
+	ref: ForwardedRef<Element>,
 ) {
-	const context = usePrismicContext();
+	const {
+		field,
+		document: doc,
+		linkResolver,
+		internalComponent,
+		externalComponent,
+		children,
+		...restProps
+	} = props;
+
+	if (DEV) {
+		if (field) {
+			if (!field.link_type) {
+				console.error(
+					`[PrismicLink] This "field" prop value caused an error to be thrown.\n`,
+					field,
+				);
+				throw new Error(
+					`[PrismicLink] The provided field is missing required properties to properly render a link. The link will not render. For more details, see ${devMsg(
+						"missing-link-properties",
+					)}`,
+				);
+			} else if (
+				("text" in field
+					? Object.keys(field).length > 2
+					: Object.keys(field).length > 1) &&
+				!("url" in field || "uid" in field || "id" in field)
+			) {
+				console.warn(
+					`[PrismicLink] The provided field is missing required properties to properly render a link. The link may not render correctly. For more details, see ${devMsg(
+						"missing-link-properties",
+					)}`,
+					field,
+				);
+			}
+		} else if (doc) {
+			if (!("url" in doc || "id" in doc)) {
+				console.warn(
+					`[PrismicLink] The provided document is missing required properties to properly render a link. The link may not render correctly. For more details, see ${devMsg(
+						"missing-link-properties",
+					)}`,
+					doc,
+				);
+			}
+		}
+	}
+
+	const {
+		href: computedHref,
+		rel: computedRel,
+		...attrs
+	} = asLinkAttrs(field ?? doc, {
+		linkResolver,
+		rel: typeof restProps.rel === "function" ? restProps.rel : undefined,
+	});
+
+	let rel: string | undefined = computedRel;
+	if ("rel" in restProps && typeof restProps.rel !== "function") {
+		rel = restProps.rel;
+	}
+
+	const href = ("href" in restProps ? restProps.href : computedHref) || "";
+
+	const InternalComponent = (internalComponent ||
+		defaultComponent) as ComponentType<LinkProps>;
+	const ExternalComponent = (externalComponent ||
+		defaultComponent) as ComponentType<LinkProps>;
+	const Component = href
+		? isInternalURL(href)
+			? InternalComponent
+			: ExternalComponent
+		: InternalComponent;
 
 	return (
-		<ServerPrismicLink
-			ref={ref}
-			linkResolver={context.linkResolver}
-			internalComponent={context.internalLinkComponent}
-			externalComponent={context.externalLinkComponent}
-			{...props}
-		/>
+		<Component ref={ref} {...attrs} {...restProps} href={href} rel={rel}>
+			{"children" in props ? children : field?.text}
+		</Component>
 	);
 }) as <
-	InternalComponentProps = React.ComponentProps<typeof defaultComponent>,
-	ExternalComponentProps = React.ComponentProps<typeof defaultComponent>,
+	InternalComponentProps = ComponentProps<typeof defaultComponent>,
+	ExternalComponentProps = ComponentProps<typeof defaultComponent>,
 >(
 	props: PrismicLinkProps<InternalComponentProps, ExternalComponentProps> & {
-		ref?: React.ForwardedRef<Element>;
+		ref?: ForwardedRef<Element>;
 	},
-) => JSX.Element;
+) => ReactNode;
+
+/**
+ * Determines if a URL is internal or external.
+ *
+ * @param url - The URL to check if internal or external.
+ *
+ * @returns `true` if `url` is internal, `false` otherwise.
+ */
+// TODO: This does not detect all relative URLs as internal such as `about` or `./about`. This function assumes relative URLs start with a "/" or "#"`.
+export function isInternalURL(url: string): boolean {
+	const isInternal = /^(\/(?!\/)|#)/.test(url);
+	const isSpecialLink = !isInternal && !/^https?:\/\//.test(url);
+
+	return isInternal && !isSpecialLink;
+}