@prismicio/next 2.2.3 → 2.2.4-pr.114.343dd9b

package/src/PrismicPreviewClient.tsx

@@ -1,16 +1,16 @@
-"use client";
+"use client"
 
-import { cookie as prismicCookie } from "@prismicio/client";
-import { useRouter } from "next/navigation";
-import type { FC } from "react";
-import { useEffect } from "react";
+import { cookie as prismicCookie } from "@prismicio/client"
+import { useRouter } from "next/navigation"
+import type { FC } from "react"
+import { useEffect } from "react"
 
 type PrismicPreviewClientProps = {
-	repositoryName: string;
-	isDraftMode: boolean;
-	updatePreviewURL?: string;
-	exitPreviewURL?: string;
-};
+	repositoryName: string
+	isDraftMode: boolean
+	updatePreviewURL?: string
+	exitPreviewURL?: string
+}
 
 export const PrismicPreviewClient: FC<PrismicPreviewClientProps> = (props) => {
 	const {
@@ -18,25 +18,25 @@ export const PrismicPreviewClient: FC<PrismicPreviewClientProps> = (props) => {
 		isDraftMode,
 		updatePreviewURL = "/api/preview",
 		exitPreviewURL = "/api/exit-preview",
-	} = props;
+	} = props
 
-	const { refresh } = useRouter();
+	const { refresh } = useRouter()
 
 	useEffect(() => {
-		const controller = new AbortController();
+		const controller = new AbortController()
 
 		window.addEventListener("prismicPreviewUpdate", onUpdate, {
 			signal: controller.signal,
-		});
+		})
 		window.addEventListener("prismicPreviewEnd", onEnd, {
 			signal: controller.signal,
-		});
+		})
 
-		const cookie = getPrismicPreviewCookie(window.document.cookie);
+		const cookie = getPrismicPreviewCookie(window.document.cookie)
 		const cookieRepositoryName = cookie
 			? (decodeURIComponent(cookie).match(/"([^"]+)\.prismic\.io"/) || [])[1]
-			: undefined;
-		const hasCookieForRepository = cookieRepositoryName === repositoryName;
+			: undefined
+		const hasCookieForRepository = cookieRepositoryName === repositoryName
 
 		// Start the preview for preview share links. Previews from
 		// share links do not go to the `updatePreviewURL` like a normal
@@ -55,75 +55,73 @@ export const PrismicPreviewClient: FC<PrismicPreviewClientProps> = (props) => {
 					if (res.type !== "opaqueredirect") {
 						console.error(
 							`[<PrismicPreview>] Failed to start the preview using "${updatePreviewURL}". Does it exist?`,
-						);
+						)
 
-						return;
+						return
 					}
 
-					refresh();
+					refresh()
 				})
 				.catch(() => {
 					// noop
-				});
+				})
 		}
 
 		function onUpdate(event: Event) {
-			event.preventDefault();
-			refresh();
+			event.preventDefault()
+			refresh()
 		}
 
 		function onEnd(event: Event) {
-			event.preventDefault();
+			event.preventDefault()
 			globalThis
 				.fetch(exitPreviewURL, { signal: controller.signal })
 				.then((res) => {
 					if (!res.ok) {
 						console.error(
 							`[<PrismicPreview>] Failed to exit Preview Mode using the "${exitPreviewURL}" API endpoint. Does it exist?`,
-						);
+						)
 
-						return;
+						return
 					}
 
-					refresh();
+					refresh()
 				})
 				.catch(() => {
 					// noop
-				});
+				})
 		}
 
-		return () => controller.abort();
-	}, [repositoryName, isDraftMode, updatePreviewURL, exitPreviewURL, refresh]);
+		return () => controller.abort()
+	}, [repositoryName, isDraftMode, updatePreviewURL, exitPreviewURL, refresh])
 
-	return null;
-};
+	return null
+}
 
 /**
  * Returns the value of a cookie from a given cookie store.
  *
- * @param cookieJar - The stringified cookie store from which to read the
- *   cookie.
- *
+ * @param cookieJar - The stringified cookie store from which to read the cookie.
  * @returns The value of the cookie, if it exists.
  */
 function getPrismicPreviewCookie(cookieJar: string): string | undefined {
 	function readValue(value: string): string {
-		return value.replace(/%3B/g, ";");
+		return value.replace(/%3B/g, ";")
 	}
 
-	const cookies = cookieJar.split("; ");
+	const cookies = cookieJar.split("; ")
 
-	let value: string | undefined;
+	let value: string | undefined
 
 	for (const cookie of cookies) {
-		const parts = cookie.split("=");
-		const name = readValue(parts[0]).replace(/%3D/g, "=");
+		const parts = cookie.split("=")
+		const name = readValue(parts[0]).replace(/%3D/g, "=")
 
 		if (name === prismicCookie.preview) {
-			value = readValue(parts.slice(1).join("="));
-			continue;
+			value = readValue(parts.slice(1).join("="))
+			continue
 		}
 	}
 
-	return value;
+	return value
 }

package/src/SliceSimulator.tsx

@@ -1,39 +1,34 @@
-"use client";
+"use client"
 
-import { SliceSimulatorWrapper } from "./SliceSimulatorWrapper";
-import { getSlices } from "./getSlices";
-import {
-	SimulatorManager,
-	StateEventType,
-	getDefaultMessage,
-} from "@prismicio/simulator/kit";
-import type { SliceSimulatorProps as BaseSliceSimulatorProps } from "@prismicio/simulator/kit";
-import { compressToEncodedURIComponent } from "lz-string";
-import { useRouter } from "next/navigation";
-import { useEffect, useState } from "react";
-import type { FC, ReactNode } from "react";
+import { SimulatorManager, StateEventType, getDefaultMessage } from "@prismicio/simulator/kit"
+import type { SliceSimulatorProps as BaseSliceSimulatorProps } from "@prismicio/simulator/kit"
+import { compressToEncodedURIComponent } from "lz-string"
+import { useRouter } from "next/navigation"
+import { useEffect, useState } from "react"
+import type { FC, ReactNode } from "react"
 
-const STATE_PARAMS_KEY = "state";
+import { getSlices } from "./getSlices"
+import { SliceSimulatorWrapper } from "./SliceSimulatorWrapper"
 
-const simulatorManager = new SimulatorManager();
+const STATE_PARAMS_KEY = "state"
 
-/**
- * Parameters provided to the Slice Simulator page.
- */
+const simulatorManager = new SimulatorManager()
+
+/** Parameters provided to the Slice Simulator page. */
 export type SliceSimulatorParams = {
 	searchParams: Promise<{
-		state?: string;
-	}>;
-};
+		state?: string
+	}>
+}
 
 export type SliceSimulatorProps = BaseSliceSimulatorProps & {
-	children: ReactNode;
-	className?: string;
-};
+	children: ReactNode
+	className?: string
+}
 
 /**
- * Simulate slices in isolation. The slice simulator enables live slice
- * development in Slice Machine and live previews in the Page Builder.
+ * Simulate slices in isolation. The slice simulator enables live slice development in Slice Machine
+ * and live previews in the Page Builder.
  */
 export const SliceSimulator: FC<SliceSimulatorProps> = ({
 	children,
@@ -41,45 +36,45 @@ export const SliceSimulator: FC<SliceSimulatorProps> = ({
 	zIndex,
 	className,
 }) => {
-	const [message, setMessage] = useState(() => getDefaultMessage());
-	const router = useRouter();
+	const [message, setMessage] = useState(() => getDefaultMessage())
+	const router = useRouter()
 
 	const state =
 		typeof window !== "undefined"
 			? new URL(window.location.href).searchParams.get(STATE_PARAMS_KEY)
-			: undefined;
-	const hasSlices = getSlices(state).length > 0;
+			: undefined
+	const hasSlices = getSlices(state).length > 0
 
 	useEffect(() => {
 		simulatorManager.state.on(
 			StateEventType.Slices,
 			(newSlices) => {
-				const url = new URL(window.location.href);
+				const url = new URL(window.location.href)
 				url.searchParams.set(
 					STATE_PARAMS_KEY,
 					compressToEncodedURIComponent(JSON.stringify(newSlices)),
-				);
+				)
 
-				window.history.replaceState(null, "", url);
+				window.history.replaceState(null, "", url)
 				// Wait until the next tick to prevent URL state race conditions.
-				setTimeout(() => router.refresh(), 0);
+				setTimeout(() => router.refresh(), 0)
 			},
 			"simulator-slices",
-		);
+		)
 		simulatorManager.state.on(
 			StateEventType.Message,
 			(newMessage) => setMessage(newMessage),
 			"simulator-message",
-		);
+		)
 
-		simulatorManager.init();
+		simulatorManager.init()
 
 		return () => {
-			simulatorManager.state.off(StateEventType.Slices, "simulator-slices");
+			simulatorManager.state.off(StateEventType.Slices, "simulator-slices")
 
-			simulatorManager.state.off(StateEventType.Message, "simulator-message");
-		};
-	}, [router]);
+			simulatorManager.state.off(StateEventType.Message, "simulator-message")
+		}
+	}, [router])
 
 	return (
 		<SliceSimulatorWrapper
@@ -91,5 +86,5 @@ export const SliceSimulator: FC<SliceSimulatorProps> = ({
 		>
 			{children}
 		</SliceSimulatorWrapper>
-	);
-};
+	)
+}

package/src/SliceSimulatorWrapper.tsx

@@ -4,21 +4,18 @@ import {
 	onClickHandler,
 	simulatorClass,
 	simulatorRootClass,
-} from "@prismicio/simulator/kit";
-import type { SliceSimulatorProps } from "@prismicio/simulator/kit";
-import type { FC, ReactNode } from "react";
+} from "@prismicio/simulator/kit"
+import type { SliceSimulatorProps } from "@prismicio/simulator/kit"
+import type { FC, ReactNode } from "react"
 
 type SliceSimulatorWrapperProps = SliceSimulatorProps & {
-	children: ReactNode;
-	className?: string;
-	message?: string;
-	hasSlices: boolean;
-};
+	children: ReactNode
+	className?: string
+	message?: string
+	hasSlices: boolean
+}
 
-/**
- * A wrapper for the slice simulator that isolates the given children from the
- * page's layout.
- */
+/** A wrapper for the slice simulator that isolates the given children from the page's layout. */
 export const SliceSimulatorWrapper: FC<SliceSimulatorWrapperProps> = ({
 	className,
 	children,
@@ -27,16 +24,13 @@ export const SliceSimulatorWrapper: FC<SliceSimulatorWrapperProps> = ({
 	message,
 	hasSlices,
 }) => {
-	const defaultProps = getDefaultProps();
+	const defaultProps = getDefaultProps()
 
 	return (
 		<div
 			className={[simulatorClass, className].filter(Boolean).join(" ")}
 			style={{
-				zIndex:
-					typeof zIndex === "undefined"
-						? defaultProps.zIndex
-						: (zIndex ?? undefined),
+				zIndex: typeof zIndex === "undefined" ? defaultProps.zIndex : (zIndex ?? undefined),
 				position: "fixed",
 				top: 0,
 				left: 0,
@@ -44,9 +38,7 @@ export const SliceSimulatorWrapper: FC<SliceSimulatorWrapperProps> = ({
 				height: "100vh",
 				overflow: "auto",
 				background:
-					typeof background === "undefined"
-						? defaultProps.background
-						: (background ?? undefined),
+					typeof background === "undefined" ? defaultProps.background : (background ?? undefined),
 			}}
 		>
 			{message ? (
@@ -56,13 +48,11 @@ export const SliceSimulatorWrapper: FC<SliceSimulatorWrapperProps> = ({
 					id="root"
 					className={simulatorRootClass}
 					onClickCapture={onClickHandler as unknown as React.MouseEventHandler}
-					onSubmitCapture={
-						disableEventHandler as unknown as React.FormEventHandler
-					}
+					onSubmitCapture={disableEventHandler as unknown as React.FormEventHandler}
 				>
 					{children}
 				</div>
 			) : null}
 		</div>
-	);
-};
+	)
+}

package/src/cacheTagPrismicPages.ts

@@ -0,0 +1,20 @@
+import type { PrismicDocument } from "@prismicio/client"
+import { cacheTag } from "next/cache"
+
+import { getPrismicCacheTags } from "./getPrismicCacheTags"
+
+/**
+ * Tags the current cache entry with cache tags for a set of Prismic pages so they can be
+ * revalidated when their content changes.
+ *
+ * Linked documents (via content relationships) are tagged as well, so the cache entry is
+ * revalidated when any of its nested documents change.
+ *
+ * @param pages - A set of Prismic pages used to tag the cache entry.
+ * @experimental
+ *
+ * @see {@link https://nextjs.org/docs/app/api-reference/functions/cacheTag}
+ */
+export function cacheTagPrismicPages(pages: PrismicDocument[]): void {
+	cacheTag(...getPrismicCacheTags(pages))
+}

package/src/createLocaleRedirect.ts

@@ -1,4 +1,4 @@
-import { devMsg } from "./lib/devMsg";
+import { devMsg } from "./lib/devMsg"
 
 /**
  * @deprecated `createLocaleRedirect()` has been removed due to performance
@@ -9,10 +9,10 @@ export function createLocaleRedirect(): never {
 		`createLocaleRedirect() has been removed due to performance issues. See ${devMsg(
 			"replace-createLocaleRedirect",
 		)} for more details.`,
-	);
+	)
 }
 /**
  * @deprecated `createLocaleRedirect()` has been removed due to performance
  *   issues.
  */
-export type CreateLocaleRedirectConfig = never;
+export type CreateLocaleRedirectConfig = never

package/src/enableAutoPreviews.ts

@@ -1,4 +1,6 @@
-import { type Client, cookie as prismicCookie } from "@prismicio/client";
+import type { Client } from "@prismicio/client"
+
+import { getPreviewRef } from "./getPreviewRef"
 
 /** Configuration for `enableAutoPreviews`. */
 export type EnableAutoPreviewsConfig = {
@@ -6,48 +8,16 @@ export type EnableAutoPreviewsConfig = {
 	// `Pick` is used to use the smallest possible subset of
 	// `prismic.Client`. Doing this reduces the surface area for breaking
 	// type changes.
-	client: Pick<Client, "queryContentFromRef" | "enableAutoPreviewsFromReq">;
-};
+	client: Pick<Client, "queryContentFromRef" | "enableAutoPreviewsFromReq">
+}
 
 /**
- * Configures a Prismic client to automatically query draft content during a
- * preview session.
+ * Configures a Prismic client to automatically query draft content during a preview session.
  *
  * @param config - Configuration for the function.
  */
 export function enableAutoPreviews(config: EnableAutoPreviewsConfig): void {
 	// We use a function value so the cookie is checked on every
 	// request. We don't have a static value to read from.
-	config.client.queryContentFromRef(async () => {
-		// Need this to avoid the following Next.js build-time error:
-		// You're importing a component that needs next/headers. That only works
-		// in a Server Component which is not supported in the pages/ directory.
-		const { cookies, draftMode } = await import("next/headers");
-
-		let isDraftModeEnabled = false;
-		try {
-			isDraftModeEnabled = (await draftMode()).isEnabled;
-		} catch {
-			// `draftMode()` may have been called in a palce that
-			// does not have access to its async storage. This
-			// occurs in places like `generateStaticParams()`. We
-			// can ignore this case.
-			return;
-		}
-		if (!isDraftModeEnabled) {
-			return;
-		}
-
-		const cookie = (await cookies()).get(prismicCookie.preview)?.value;
-		if (!cookie) {
-			return;
-		}
-
-		const isActiveCookie = cookie.includes("websitePreviewId=");
-		if (!isActiveCookie) {
-			return;
-		}
-
-		return cookie;
-	});
+	config.client.queryContentFromRef(() => getPreviewRef())
 }

package/src/exitPreview.ts

@@ -1,31 +1,36 @@
+import { cookie as prismicCookie } from "@prismicio/client"
+
 /**
- * Ends a Prismic preview session within a Next.js app. This function should be
- * used in a Router Handler.
+ * Ends a Prismic preview session within a Next.js app. This function should be used in a Router
+ * Handler.
  *
  * @example
+ * 	;```typescript
+ * 	// src/app/api/exit-preview/route.js
  *
- * ```typescript
- * // src/app/api/exit-preview/route.js
- *
- * import { exitPreview } from "@prismicio/next";
+ * 	import { exitPreview } from "@prismicio/next"
  *
- * export async function GET() {
- * 	return await exitPreview();
- * }
- * ```
+ * 	export async function GET() {
+ * 		return await exitPreview()
+ * 	}
+ * 	```
  */
 export async function exitPreview(): Promise<Response> {
 	// Need this to avoid the following Next.js build-time error:
 	// You're importing a component that needs next/headers. That only works
 	// in a Server Component which is not supported in the pages/ directory.
-	const { draftMode } = await import("next/headers");
+	const { cookies, draftMode } = await import("next/headers")
+
+	;(await draftMode()).disable()
 
-	(await draftMode()).disable();
+	// `redirectToPreviewURL` writes the preview cookie, so `exitPreview`
+	// clears it to close the preview-cookie loop.
+	;(await cookies()).delete(prismicCookie.preview)
 
 	// `Cache-Control` header is used to prevent CDN-level caching.
 	return new Response(JSON.stringify({ success: true }), {
 		headers: {
 			"Cache-Control": "no-store",
 		},
-	});
+	})
 }

package/src/getPreviewRef.ts

@@ -0,0 +1,51 @@
+import { cookie as prismicCookie } from "@prismicio/client"
+
+/**
+ * Reads the Prismic preview ref for the current request when an active preview session exists.
+ *
+ * This is the read-side counterpart to `redirectToPreviewURL`, which writes the preview cookie. Use
+ * it with Next.js Cache Components to read the ref _outside_ a cached function and pass it _in_ as
+ * an argument so it becomes part of the cache key:
+ *
+ * @example
+ * 	;```typescript
+ * 	import { getPreviewRef } from "@prismicio/next"
+ *
+ * 	const page = await fetchPage(uid, await getPreviewRef())
+ * 	```
+ *
+ * @returns The active preview ref, or `undefined` if no preview session is active.
+ * @experimental
+ */
+export async function getPreviewRef(): Promise<string | undefined> {
+	// Need this to avoid the following Next.js build-time error:
+	// You're importing a component that needs next/headers. That only works
+	// in a Server Component which is not supported in the pages/ directory.
+	const { cookies, draftMode } = await import("next/headers")
+
+	let isDraftModeEnabled = false
+	try {
+		isDraftModeEnabled = (await draftMode()).isEnabled
+	} catch {
+		// `draftMode()` may have been called in a place that
+		// does not have access to its async storage. This
+		// occurs in places like `generateStaticParams()`. We
+		// can ignore this case.
+		return
+	}
+	if (!isDraftModeEnabled) {
+		return
+	}
+
+	const cookie = (await cookies()).get(prismicCookie.preview)?.value
+	if (!cookie) {
+		return
+	}
+
+	const isActiveCookie = cookie.includes("websitePreviewId=")
+	if (!isActiveCookie) {
+		return
+	}
+
+	return cookie
+}

package/src/getPrismicCacheTags.ts

@@ -0,0 +1,46 @@
+import type { PrismicDocument } from "@prismicio/client"
+
+const CACHE_TAG_PREFIX = "prismic/"
+
+/**
+ * Generates cache tags for a set of Prismic pages. Tags for linked pages (e.g. a content
+ * relationship) are included to ensure all related content can be revalidated.
+ *
+ * @param pages - A set of Prismic pages used to tag the function.
+ * @experimental
+ *
+ * @see {@link https://nextjs.org/docs/app/api-reference/functions/cacheTag}
+ */
+export function getPrismicCacheTags(pages: PrismicDocument[]): string[] {
+	const ids = [...new Set(getPrismicDocumentIDs(pages))]
+	return ids.map((id) => buildPrismicCacheTag(id))
+}
+
+export function buildPrismicCacheTag(id: string): string {
+	return `${CACHE_TAG_PREFIX}${id}`
+}
+
+function getPrismicDocumentIDs(input: unknown): string[] {
+	if (typeof input !== "object" || input == null) return []
+
+	if (Array.isArray(input)) return input.flatMap((item) => getPrismicDocumentIDs(item))
+
+	if ("id" in input && typeof input.id === "string") {
+		// Document
+		// Content relationship or link
+		if (
+			("href" in input &&
+				typeof input.href === "string" &&
+				input.href.includes("/api/v2/documents/search?")) ||
+			("link_type" in input && input.link_type === "Document")
+		) {
+			if ("data" in input && typeof input.data === "object" && input.data !== null) {
+				return [input.id, ...getPrismicDocumentIDs(input.data)]
+			} else {
+				return [input.id]
+			}
+		}
+	}
+
+	return Object.values(input).flatMap((input) => getPrismicDocumentIDs(input))
+}

package/src/getSlices.ts

@@ -1,11 +1,7 @@
-import { getDefaultSlices } from "@prismicio/simulator/kit";
-import type { StateEvents, StateEventType } from "@prismicio/simulator/kit";
-import { decompressFromEncodedURIComponent } from "lz-string";
+import { getDefaultSlices } from "@prismicio/simulator/kit"
+import type { StateEvents, StateEventType } from "@prismicio/simulator/kit"
+import { decompressFromEncodedURIComponent } from "lz-string"
 
-export const getSlices = (
-	state: string | null | undefined,
-): StateEvents[StateEventType.Slices] => {
-	return state
-		? JSON.parse(decompressFromEncodedURIComponent(state))
-		: getDefaultSlices();
-};
+export const getSlices = (state: string | null | undefined): StateEvents[StateEventType.Slices] => {
+	return state ? JSON.parse(decompressFromEncodedURIComponent(state)) : getDefaultSlices()
+}

package/src/imgixLoader.ts

@@ -1,26 +1,26 @@
-import type { ImageLoaderProps } from "next/image";
-import type { ImgixURLParams } from "imgix-url-builder";
-import { buildURL } from "imgix-url-builder";
+import type { ImgixURLParams } from "imgix-url-builder"
+import { buildURL } from "imgix-url-builder"
+import type { ImageLoaderProps } from "next/image"
 
 /**
- * A `next/image` loader for Imgix, which Prismic uses, with an optional
- * collection of default Imgix parameters.
+ * A `next/image` loader for Imgix, which Prismic uses, with an optional collection of default Imgix
+ * parameters.
  *
  * @see To learn about `next/image` loaders: https://nextjs.org/docs/api-reference/next/image#loader
  * @see To learn about Imgix's URL API: https://docs.imgix.com/apis/rendering
  */
 export const imgixLoader = (args: ImageLoaderProps): string => {
-	const url = new URL(args.src);
+	const url = new URL(args.src)
 
 	const params: ImgixURLParams = {
 		fit: (url.searchParams.get("fit") as ImgixURLParams["fit"]) || "max",
 		w: args.width,
 		h: undefined,
-	};
+	}
 
 	if (args.quality) {
-		params.q = args.quality;
+		params.q = args.quality
 	}
 
-	return buildURL(args.src, params);
-};
+	return buildURL(args.src, params)
+}