@prismicio/react 2.5.2 → 2.6.0-alpha.0

package/src/PrismicToolbar.tsx

@@ -1,4 +1,7 @@
+"use client";
+
 import * as React from "react";
+import { getToolbarSrc } from "@prismicio/client";
 
 /**
  * Props for `<PrismicToolbar>`.
@@ -13,6 +16,8 @@ export type PrismicToolbarProps = {
 	/**
 	 * 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";
@@ -24,11 +29,8 @@ export type PrismicToolbarProps = {
  */
 export const PrismicToolbar = ({
 	repositoryName,
-	type = "new",
 }: PrismicToolbarProps): null => {
-	const src = `https://static.cdn.prismic.io/prismic.js?repo=${repositoryName}${
-		type === "new" ? "&new=true" : ""
-	}`;
+	const src = getToolbarSrc(repositoryName);
 
 	React.useEffect(() => {
 		const existingScript = document.querySelector(`script[src="${src}"]`);
@@ -41,7 +43,6 @@ export const PrismicToolbar = ({
 			// Used to distinguish the toolbar element from other elements.
 			script.dataset.prismicToolbar = "";
 			script.dataset.repositoryName = repositoryName;
-			script.dataset.type = type;
 
 			// Disable Happy DOM `<script>` evaluation during
 			// tests.
@@ -58,7 +59,7 @@ export const PrismicToolbar = ({
 
 			document.body.appendChild(script);
 		}
-	}, [repositoryName, type, src]);
+	}, [repositoryName, src]);
 
 	return null;
 };

package/src/SliceZone.tsx

@@ -1,19 +1,7 @@
 import * as React from "react";
-import * as prismicT from "@prismicio/types";
+import * as prismic from "@prismicio/client";
 
 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
@@ -25,7 +13,7 @@ type ExtractSliceType<Slice extends SliceLike> = Slice extends SliceLikeRestV2
  * @typeParam SliceType - Type name of the Slice.
  */
 export type SliceLikeRestV2<SliceType extends string = string> = {
-	slice_type: prismicT.Slice<SliceType>["slice_type"];
+	slice_type: prismic.Slice<SliceType>["slice_type"];
 	id?: string;
 };
 
@@ -36,7 +24,7 @@ export type SliceLikeRestV2<SliceType extends string = string> = {
  * @typeParam SliceType - Type name of the Slice.
  */
 export type SliceLikeGraphQL<SliceType extends string = string> = {
-	type: prismicT.Slice<SliceType>["slice_type"];
+	type: prismic.Slice<SliceType>["slice_type"];
 };
 
 /**
@@ -115,37 +103,6 @@ export type SliceComponentType<
 	TContext = unknown,
 > = React.ComponentType<SliceComponentProps<TSlice, TContext>>;
 
-/**
- * A record of Slice types mapped to a React component. The component will be
- * rendered for each instance of its Slice.
- *
- * @deprecated This type is no longer used by `@prismicio/react`. Prefer using
- *   `Record<string, SliceComponentType<any>>` instead.
- * @typeParam TSlice - The type(s) of a Slice in the Slice Zone.
- * @typeParam TContext - Arbitrary data made available to all Slice components.
- */
-export type SliceZoneComponents<
-	TSlice extends SliceLike = SliceLike,
-	TContext = unknown,
-> =
-	// This is purposely not wrapped in Partial to ensure a component is provided
-	// for all Slice types. <SliceZone> will render a default component if one is
-	// not provided, but it *should* be a type error if an explicit component is
-	// missing.
-	//
-	// If a developer purposely does not want to provide a component, they can
-	// assign it to the TODOSliceComponent exported from this package. This
-	// signals to future developers that it is a placeholder and should be
-	// implemented.
-	{
-		[SliceType in ExtractSliceType<TSlice>]: SliceComponentType<
-			Extract<TSlice, SliceLike<SliceType>> extends never
-				? SliceLike
-				: Extract<TSlice, SliceLike<SliceType>>,
-			TContext
-		>;
-	};
-
 /**
  * This Slice component can be used as a reminder to provide a proper
  * implementation.
@@ -160,12 +117,9 @@ export const TODOSliceComponent = __PRODUCTION__
 	  }: 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 "${type}"`,
-					slice,
-				);
-			}, [slice, type]);
+			console.warn(
+				`[SliceZone] Could not find a component for Slice type "${type}"`,
+			);
 
 			return (
 				<section data-slice-zone-todo-component="" data-slice-type={type}>
@@ -175,54 +129,6 @@ export const TODOSliceComponent = __PRODUCTION__
 			);
 	  };
 
-/**
- * Arguments for a `<SliceZone>` `resolver` function.
- */
-type SliceZoneResolverArgs<
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	TSlice extends SliceLike = any,
-> = {
-	/**
-	 * The Slice to resolve to a React component.
-	 */
-	slice: TSlice;
-
-	/**
-	 * The name of the Slice.
-	 */
-	sliceName: PascalCase<ExtractSliceType<TSlice>>;
-
-	/**
-	 * The index of the Slice in the Slice Zone.
-	 */
-	i: number;
-};
-
-/**
- * A function that determines the rendered React component for each Slice in the
- * Slice Zone. If a nullish value is returned, the component will fallback to
- * the `components` or `defaultComponent` props to determine the rendered
- * component.
- *
- * @deprecated Use the `components` prop instead.
- *
- * @param args - Arguments for the resolver function.
- *
- * @returns The React component to render for a Slice.
- */
-export type SliceZoneResolver<
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	TSlice extends SliceLike = any,
-	TContext = unknown,
-> = (args: SliceZoneResolverArgs<TSlice>) =>
-	| SliceComponentType<
-			// eslint-disable-next-line @typescript-eslint/no-explicit-any
-			any,
-			TContext
-	  >
-	| undefined
-	| null;
-
 /**
  * React props for the `<SliceZone>` component.
  *
@@ -241,19 +147,6 @@ export type SliceZoneProps<TContext = unknown> = {
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	components?: Record<string, SliceComponentType<any, TContext>>;
 
-	/**
-	 * A function that determines the rendered React component for each Slice in
-	 * the Slice Zone.
-	 *
-	 * @deprecated Use the `components` prop instead.
-	 *
-	 * @param args - Arguments for the resolver function.
-	 *
-	 * @returns The React component to render for a Slice.
-	 */
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	resolver?: SliceZoneResolver<any, TContext>;
-
 	/**
 	 * The React component rendered if a component mapping from the `components`
 	 * prop cannot be found.
@@ -285,7 +178,6 @@ export type SliceZoneProps<TContext = unknown> = {
 export const SliceZone = <TContext,>({
 	slices = [],
 	components = {},
-	resolver,
 	defaultComponent = TODOSliceComponent,
 	context = {} as TContext,
 }: SliceZoneProps<TContext>): JSX.Element => {
@@ -293,22 +185,9 @@ export const SliceZone = <TContext,>({
 		return slices.map((slice, index) => {
 			const type = "slice_type" in slice ? slice.slice_type : slice.type;
 
-			let Comp =
+			const Comp =
 				components[type as keyof typeof components] || defaultComponent;
 
-			// TODO: Remove `resolver` in v3 in favor of `components`.
-			if (resolver) {
-				const resolvedComp = resolver({
-					slice,
-					sliceName: pascalCase(type),
-					i: index,
-				});
-
-				if (resolvedComp) {
-					Comp = resolvedComp as typeof Comp;
-				}
-			}
-
 			const key =
 				"id" in slice && slice.id
 					? slice.id
@@ -324,7 +203,7 @@ export const SliceZone = <TContext,>({
 				/>
 			);
 		});
-	}, [components, context, defaultComponent, slices, resolver]);
+	}, [components, context, defaultComponent, slices]);
 
 	return <>{renderedSlices}</>;
 };

package/src/index.ts

@@ -17,13 +17,7 @@ export type { PrismicTextProps } from "./PrismicText";
 export { PrismicRichText } from "./PrismicRichText";
 export type { PrismicRichTextProps } from "./PrismicRichText";
 
-import { Element } from "@prismicio/richtext";
-export { Element };
-/**
- * @deprecated Renamed to `Element` (without an "s").
- */
-// TODO: Remove in v3.
-export const Elements = Element;
+export { Element } from "@prismicio/richtext";
 
 export { PrismicImage } from "./PrismicImage";
 export type { PrismicImageProps } from "./PrismicImage";
@@ -35,10 +29,8 @@ export type {
 	SliceLikeRestV2,
 	SliceLikeGraphQL,
 	SliceLike,
-	SliceZoneComponents,
 	SliceZoneLike,
 	SliceZoneProps,
-	SliceZoneResolver,
 } from "./SliceZone";
 
 export { PrismicToolbar } from "./PrismicToolbar";

package/src/react-server/PrismicLink.tsx

@@ -0,0 +1,179 @@
+import * as React from "react";
+import {
+	LinkField,
+	LinkResolverFunction,
+	PrismicDocument,
+	asLinkAttrs,
+	AsLinkAttrsConfig,
+} from "@prismicio/client";
+
+import { __PRODUCTION__ } from "../lib/__PRODUCTION__";
+import { devMsg } from "../lib/devMsg";
+import { isInternalURL } from "../lib/isInternalURL";
+
+/**
+ * The default component rendered for internal and external links.
+ */
+export 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?: React.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?: React.ReactNode;
+}
+
+export type PrismicLinkProps<
+	InternalComponentProps = React.ComponentProps<typeof defaultComponent>,
+	ExternalComponentProps = React.ComponentProps<typeof defaultComponent>,
+> = Omit<InternalComponentProps & ExternalComponentProps, "rel" | "href"> & {
+	/**
+	 * 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;
+
+	/**
+	 * 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?: React.ElementType<InternalComponentProps>;
+
+	/**
+	 * The component rendered for external URLs. Defaults to `<a>`.
+	 */
+	externalComponent?: React.ComponentType<ExternalComponentProps>;
+} & (
+		| {
+				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 = React.forwardRef(function PrismicLink<
+	InternalComponentProps = React.ComponentProps<typeof defaultComponent>,
+	ExternalComponentProps = React.ComponentProps<typeof defaultComponent>,
+>(
+	{
+		field,
+		document: doc,
+		linkResolver,
+		internalComponent,
+		externalComponent,
+		...restProps
+	}: PrismicLinkProps<InternalComponentProps, ExternalComponentProps>,
+	ref: React.ForwardedRef<Element>,
+): JSX.Element {
+	if (!__PRODUCTION__) {
+		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 (
+				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 React.ComponentType<LinkProps>;
+	const ExternalComponent = (externalComponent ||
+		defaultComponent) as React.ComponentType<LinkProps>;
+	const Component =
+		href && isInternalURL(href) ? InternalComponent : ExternalComponent;
+
+	return (
+		<Component ref={ref} {...attrs} {...restProps} href={href} rel={rel} />
+	);
+}) as <
+	InternalComponentProps = React.ComponentProps<typeof defaultComponent>,
+	ExternalComponentProps = React.ComponentProps<typeof defaultComponent>,
+>(
+	props: PrismicLinkProps<InternalComponentProps, ExternalComponentProps> & {
+		ref?: React.ForwardedRef<Element>;
+	},
+) => JSX.Element;