@prismicio/react 2.0.0-beta.3 → 2.0.0-beta.7

package/src/SliceZone.tsx

@@ -136,6 +136,44 @@ export const TODOSliceComponent = __PRODUCTION__
 			);
 	  };
 
+/**
+ * Arguments for a `<SliceZone>` `resolver` function.
+ */
+type SliceZoneResolverArgs<TSlice extends SliceLike = SliceLike> = {
+	/**
+	 * The Slice to resolve to a React component.
+	 */
+	slice: TSlice;
+
+	/**
+	 * The name of the Slice.
+	 */
+	sliceName: TSlice["slice_type"];
+
+	/**
+	 * 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<
+	TSlice extends SliceLike = SliceLike,
+	TContext = unknown,
+> = (
+	args: SliceZoneResolverArgs<TSlice>,
+) => SliceComponentType<TSlice, TContext> | undefined | null;
+
 /**
  * React props for the `<SliceZone>` component.
  *
@@ -156,6 +194,18 @@ export type SliceZoneProps<
 	 */
 	components?: SliceZoneComponents<TSlice, 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.
+	 */
+	resolver?: SliceZoneResolver<TSlice, TContext>;
+
 	/**
 	 * The React component rendered if a component mapping from the `components`
 	 * prop cannot be found.
@@ -178,20 +228,37 @@ export type SliceZoneProps<
  *
  * @typeParam TSlice - The type(s) of a Slice in the Slice Zone.
  * @typeParam TContext - Arbitrary data made available to all Slice components.
+ *
  * @returns The Slice Zone's content as React components.
+ *
  * @see Learn about Prismic Slices and Slice Zones {@link https://prismic.io/docs/core-concepts/slices}
  */
 export const SliceZone = <TSlice extends SliceLike, TContext>({
 	slices = [],
 	components = {} as SliceZoneComponents<TSlice, TContext>,
+	resolver,
 	defaultComponent = TODOSliceComponent,
 	context = {} as TContext,
 }: SliceZoneProps<TSlice, TContext>): JSX.Element => {
 	const renderedSlices = React.useMemo(() => {
 		return slices.map((slice, index) => {
-			const Comp = (components[slice.slice_type as keyof typeof components] ||
+			let Comp = (components[slice.slice_type as keyof typeof components] ||
 				defaultComponent) as SliceComponentType<TSlice, TContext>;
-			const key = JSON.stringify(slice);
+
+			// TODO: Remove `resolver` in v3 in favor of `components`.
+			if (resolver) {
+				const resolvedComp = resolver({
+					slice,
+					sliceName: slice.slice_type,
+					i: index,
+				});
+
+				if (resolvedComp) {
+					Comp = resolvedComp;
+				}
+			}
+
+			const key = `${index}-${JSON.stringify(slice)}`;
 
 			return (
 				<Comp

package/src/{hooks.ts → clientHooks.ts}

@@ -12,10 +12,13 @@ import {
  *
  * @remarks
  * An additional `@prismicio/client` instance can be provided at `params.client`.
+ *
  * @typeParam TDocument - Type of Prismic documents returned
+ *
  * @param params - Parameters to filter, sort, and paginate results
  *
  * @returns The composable payload {@link ClientHookReturnType}
+ *
  * @see Underlying `@prismicio/client` method {@link proto.get}
  */
 export const usePrismicDocuments = <TDocument extends prismicT.PrismicDocument>(
@@ -29,10 +32,13 @@ export const usePrismicDocuments = <TDocument extends prismicT.PrismicDocument>(
  *
  * @remarks
  * An additional `@prismicio/client` instance can be provided at `params.client`.
+ *
  * @typeParam TDocument - Type of the Prismic document returned
+ *
  * @param params - Parameters to filter, sort, and paginate results
  *
  * @returns The composable payload {@link ClientHookReturnType}
+ *
  * @see Underlying `@prismicio/client` method {@link proto.getFirst}
  */
 export const useFirstPrismicDocument = <
@@ -48,10 +54,13 @@ export const useFirstPrismicDocument = <
  *
  * @remarks
  * An additional `@prismicio/client` instance can be provided at `params.client`.
+ *
  * @typeParam TDocument - Type of Prismic documents returned
+ *
  * @param params - Parameters to filter and sort results
  *
  * @returns The composable payload {@link ClientHookReturnType}
+ *
  * @see Underlying `@prismicio/client` method {@link proto.getAll}
  */
 export const useAllPrismicDocumentsDangerously = <
@@ -69,11 +78,14 @@ export const useAllPrismicDocumentsDangerously = <
  *
  * @remarks
  * An additional `@prismicio/client` instance can be provided at `params.client`.
+ *
  * @typeParam TDocument - Type of the Prismic document returned
+ *
  * @param id - ID of the document
  * @param params - Parameters to filter, sort, and paginate results
  *
  * @returns The composable payload {@link ClientHookReturnType}
+ *
  * @see Underlying `@prismicio/client` method {@link proto.getByID}
  */
 export const usePrismicDocumentByID = <
@@ -91,11 +103,14 @@ export const usePrismicDocumentByID = <
  *
  * @remarks
  * An additional `@prismicio/client` instance can be provided at `params.client`.
+ *
  * @typeParam TDocument - Type of Prismic documents returned
+ *
  * @param ids - A list of document IDs
  * @param params - Parameters to filter, sort, and paginate results
  *
  * @returns The composable payload {@link ClientHookReturnType}
+ *
  * @see Underlying `@prismicio/client` method {@link proto.getByIDs}
  */
 export const usePrismicDocumentsByIDs = <
@@ -113,11 +128,14 @@ export const usePrismicDocumentsByIDs = <
  *
  * @remarks
  * An additional `@prismicio/client` instance can be provided at `params.client`.
+ *
  * @typeParam TDocument - Type of Prismic documents returned
+ *
  * @param ids - A list of document IDs
  * @param params - Parameters to filter and sort results
  *
  * @returns The composable payload {@link ClientHookReturnType}
+ *
  * @see Underlying `@prismicio/client` method {@link proto.getAllByIDs}
  */
 export const useAllPrismicDocumentsByIDs = <
@@ -136,12 +154,15 @@ export const useAllPrismicDocumentsByIDs = <
  *
  * @remarks
  * An additional `@prismicio/client` instance can be provided at `params.client`.
+ *
  * @typeParam TDocument - Type of the Prismic document returned
+ *
  * @param documentType - The API ID of the document's Custom Type
  * @param uid - UID of the document
  * @param params - Parameters to filter, sort, and paginate results
  *
  * @returns The composable payload {@link ClientHookReturnType}
+ *
  * @see Underlying `@prismicio/client` method {@link proto.getByUID}
  */
 export const usePrismicDocumentByUID = <
@@ -161,12 +182,15 @@ export const usePrismicDocumentByUID = <
  *
  * @remarks
  * An additional `@prismicio/client` instance can be provided at `params.client`.
+ *
  * @typeParam TDocument - Type of the Prismic document returned
+ *
  * @param documentType - The API ID of the document's Custom Type
  * @param uids - A list of document UIDs.
  * @param params - Parameters to filter, sort, and paginate results
  *
  * @returns The composable payload {@link ClientHookReturnType}
+ *
  * @see Underlying `@prismicio/client` method {@link proto.getByUID}
  */
 export const usePrismicDocumentsByUIDs = <
@@ -186,12 +210,15 @@ export const usePrismicDocumentsByUIDs = <
  *
  * @remarks
  * An additional `@prismicio/client` instance can be provided at `params.client`.
+ *
  * @typeParam TDocument - Type of the Prismic document returned
+ *
  * @param documentType - The API ID of the document's Custom Type
  * @param uids - A list of document UIDs.
  * @param params - Parameters to filter, sort, and paginate results
  *
  * @returns The composable payload {@link ClientHookReturnType}
+ *
  * @see Underlying `@prismicio/client` method {@link proto.getByUID}
  */
 export const useAllPrismicDocumentsByUIDs = <
@@ -211,11 +238,14 @@ export const useAllPrismicDocumentsByUIDs = <
  *
  * @remarks
  * An additional `@prismicio/client` instance can be provided at `params.client`.
+ *
  * @typeParam TDocument - Type of the Prismic document returned
+ *
  * @param documentType - The API ID of the singleton Custom Type
  * @param params - Parameters to filter, sort, and paginate results
  *
  * @returns The composable payload {@link ClientHookReturnType}
+ *
  * @see Underlying `@prismicio/client` method {@link proto.getSingle}
  */
 export const useSinglePrismicDocument = <
@@ -233,11 +263,14 @@ export const useSinglePrismicDocument = <
  *
  * @remarks
  * An additional `@prismicio/client` instance can be provided at `params.client`.
+ *
  * @typeParam TDocument - Type of Prismic documents returned
+ *
  * @param documentType - The API ID of the Custom Type
  * @param params - Parameters to filter, sort, and paginate results
  *
  * @returns The composable payload {@link ClientHookReturnType}
+ *
  * @see Underlying `@prismicio/client` method {@link proto.getByType}
  */
 export const usePrismicDocumentsByType = <
@@ -256,11 +289,14 @@ export const usePrismicDocumentsByType = <
  *
  * @remarks
  * An additional `@prismicio/client` instance can be provided at `params.client`.
+ *
  * @typeParam TDocument - Type of Prismic documents returned
+ *
  * @param documentType - The API ID of the Custom Type
  * @param params - Parameters to filter and sort results
  *
  * @returns The composable payload {@link ClientHookReturnType}
+ *
  * @see Underlying `@prismicio/client` method {@link proto.getAllByType}
  */
 export const useAllPrismicDocumentsByType = <
@@ -278,11 +314,14 @@ export const useAllPrismicDocumentsByType = <
  *
  * @remarks
  * An additional `@prismicio/client` instance can be provided at `params.client`.
+ *
  * @typeParam TDocument - Type of Prismic documents returned
+ *
  * @param tag - The tag that must be included on a document
  * @param params - Parameters to filter, sort, and paginate results
  *
  * @returns The composable payload {@link ClientHookReturnType}
+ *
  * @see Underlying `@prismicio/client` method {@link proto.getByTag}
  */
 export const usePrismicDocumentsByTag = <
@@ -300,11 +339,14 @@ export const usePrismicDocumentsByTag = <
  *
  * @remarks
  * An additional `@prismicio/client` instance can be provided at `params.client`.
+ *
  * @typeParam TDocument - Type of Prismic documents returned
+ *
  * @param tag - The tag that must be included on a document
  * @param params - Parameters to filter and sort results
  *
  * @returns The composable payload {@link ClientHookReturnType}
+ *
  * @see Underlying `@prismicio/client` method {@link proto.getAllByTag}
  */
 export const useAllPrismicDocumentsByTag = <
@@ -323,11 +365,14 @@ export const useAllPrismicDocumentsByTag = <
  *
  * @remarks
  * An additional `@prismicio/client` instance can be provided at `params.client`.
+ *
  * @typeParam TDocument - Type of Prismic documents returned
+ *
  * @param tags - A list of tags that must be included on a document
  * @param params - Parameters to filter, sort, and paginate results
  *
  * @returns The composable payload {@link ClientHookReturnType}
+ *
  * @see Underlying `@prismicio/client` method {@link proto.getByTags}
  */
 export const usePrismicDocumentsBySomeTags = <
@@ -346,11 +391,14 @@ export const usePrismicDocumentsBySomeTags = <
  *
  * @remarks
  * An additional `@prismicio/client` instance can be provided at `params.client`.
+ *
  * @typeParam TDocument - Type of Prismic documents returned
+ *
  * @param tags - A list of tags that must be included on a document
  * @param params - Parameters to filter and sort results
  *
  * @returns The composable payload {@link ClientHookReturnType}
+ *
  * @see Underlying `@prismicio/client` method {@link proto.getAllByTags}
  */
 export const useAllPrismicDocumentsBySomeTags = <
@@ -369,11 +417,14 @@ export const useAllPrismicDocumentsBySomeTags = <
  *
  * @remarks
  * An additional `@prismicio/client` instance can be provided at `params.client`.
+ *
  * @typeParam TDocument - Type of Prismic documents returned
+ *
  * @param tags - A list of tags that must be included on a document
  * @param params - Parameters to filter, sort, and paginate results
  *
  * @returns The composable payload {@link ClientHookReturnType}
+ *
  * @see Underlying `@prismicio/client` method {@link proto.getByTags}
  */
 export const usePrismicDocumentsByEveryTag = <
@@ -392,11 +443,14 @@ export const usePrismicDocumentsByEveryTag = <
  *
  * @remarks
  * An additional `@prismicio/client` instance can be provided at `params.client`.
+ *
  * @typeParam TDocument - Type of Prismic documents returned
+ *
  * @param tags - A list of tags that must be included on a document
  * @param params - Parameters to filter and sort results
  *
  * @returns The composable payload {@link ClientHookReturnType}
+ *
  * @see Underlying `@prismicio/client` method {@link proto.getAllByTags}
  */
 export const useAllPrismicDocumentsByEveryTag = <

package/src/index.ts

@@ -25,11 +25,15 @@ export type {
 	SliceZoneComponents,
 	SliceZoneLike,
 	SliceZoneProps,
+	SliceZoneResolver,
 } from "./SliceZone";
 
 export { PrismicToolbar } from "./PrismicToolbar";
 export type { PrismicToolbarProps } from "./PrismicToolbar";
 
+export { usePrismicPreviewResolver } from "./usePrismicPreviewResolver";
+export type { UsePrismicPreviewResolverArgs } from "./usePrismicPreviewResolver";
+
 export {
 	useAllPrismicDocumentsDangerously,
 	useAllPrismicDocumentsByEveryTag,
@@ -49,7 +53,7 @@ export {
 	usePrismicDocumentsByType,
 	usePrismicDocumentsByUIDs,
 	useSinglePrismicDocument,
-} from "./hooks";
+} from "./clientHooks";
 
 export type {
 	JSXMapSerializer,

package/src/usePrismicPreviewResolver.ts

@@ -0,0 +1,88 @@
+import type * as prismic from "@prismicio/client";
+
+import * as React from "react";
+
+import {
+	ClientHookReturnType,
+	useStatefulPrismicClientMethod,
+} from "./useStatefulPrismicClientMethod";
+
+export type UsePrismicPreviewResolverArgs = {
+	/**
+	 * An optional `@prismicio/client` instance to override the Client provided to
+	 * `<PrismicProvider>`
+	 */
+	client?: prismic.Client;
+
+	/**
+	 * A function that maps a Prismic document to a URL within your app.
+	 */
+	linkResolver?: Parameters<
+		prismic.Client["resolvePreviewURL"]
+	>[0]["linkResolver"];
+
+	/**
+	 * A fallback URL if the Link Resolver does not return a value.
+	 */
+	defaultURL?: Parameters<prismic.Client["resolvePreviewURL"]>[0]["defaultURL"];
+
+	/**
+	 * The preview token (also known as a ref) that will be used to query preview
+	 * content from the Prismic repository.
+	 */
+	previewToken?: Parameters<
+		prismic.Client["resolvePreviewURL"]
+	>[0]["previewToken"];
+
+	/**
+	 * The previewed document that will be used to determine the destination URL.
+	 */
+	documentID?: Parameters<prismic.Client["resolvePreviewURL"]>[0]["documentID"];
+
+	/**
+	 * A function to automatically navigate to the resolved URL. If a function is
+	 * not provded, `usePreviewResolver` will not navigate to the URL.
+	 *
+	 * @param url - The resolved preview URL.
+	 */
+	navigate?: (url: string) => unknown;
+};
+
+/**
+ * Resolve a preview session's URL. The resolved URL can be used to redirect to
+ * the previewed document.
+ *
+ * If a `navigate` function is provided, the hook will automatically navigate to
+ * the previewed document's URL.
+ *
+ * @param args - Arguments to configure how a URL is resolved.
+ *
+ * @returns A tuple containing the resolved URL and the hook's state.
+ */
+export const usePrismicPreviewResolver = (
+	args: UsePrismicPreviewResolverArgs = {},
+): ClientHookReturnType<string> => {
+	const result = useStatefulPrismicClientMethod(
+		"resolvePreviewURL",
+		[
+			{
+				linkResolver: args.linkResolver,
+				defaultURL: args.defaultURL || "/",
+				previewToken: args.previewToken,
+				documentID: args.documentID,
+			},
+		],
+		args.client,
+	);
+
+	const [resolvedURL] = result;
+	const { navigate } = args;
+
+	React.useEffect(() => {
+		if (resolvedURL && navigate) {
+			navigate(resolvedURL);
+		}
+	}, [resolvedURL, navigate]);
+
+	return result;
+};

package/src/useStatefulPrismicClientMethod.ts

@@ -129,6 +129,7 @@ export type ClientHookReturnType<TData = unknown> = [
  *   will be forwarded.
  *
  * @returns A new React hook configured for the provided method.
+ *
  * @internal
  */
 export const useStatefulPrismicClientMethod = <
@@ -138,16 +139,17 @@ export const useStatefulPrismicClientMethod = <
 >(
 	methodName: TMethodName,
 	args: TArgs,
+	explicitClient?: prismic.Client,
 ): ClientHookReturnType<TData> => {
 	const lastArg = args[args.length - 1];
 	const {
-		client: explicitClient,
+		client: lastArgExplicitClient,
 		skip,
 		...params
 	} = isParams(lastArg) ? lastArg : ({} as HookOnlyParameters);
 	const argsWithoutParams = isParams(lastArg) ? args.slice(0, -1) : args;
 
-	const client = usePrismicClient(explicitClient);
+	const client = usePrismicClient(explicitClient || lastArgExplicitClient);
 
 	const [state, dispatch] = React.useReducer<
 		React.Reducer<StateMachineState<TData>, StateMachineAction<TData>>