@slicemachine/adapter-next 0.3.37-beta.7 → 0.3.37-beta.8

package/dist/simulator.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"simulator.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;"}
+{"version":3,"file":"simulator.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;"}

package/dist/simulator.js

@@ -1,5 +1,7 @@
 import { SliceSimulator } from "./simulator/SliceSimulator.js";
+import { getSlices } from "./simulator/getSlices.js";
 export {
-  SliceSimulator
+  SliceSimulator,
+  getSlices
 };
 //# sourceMappingURL=simulator.js.map

package/dist/simulator.js.map

@@ -1 +1 @@
-{"version":3,"file":"simulator.js","sources":[],"sourcesContent":[],"names":[],"mappings":";"}
+{"version":3,"file":"simulator.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slicemachine/adapter-next",
-  "version": "0.3.37-beta.7",
+  "version": "0.3.37-beta.8",
   "description": "Slice Machine adapter for Next.js.",
   "keywords": [
     "typescript",
@@ -21,9 +21,16 @@
       "import": "./dist/index.js"
     },
     "./simulator": {
-      "types": "./dist/simulator/index.d.ts",
-      "require": "./dist/simulator.cjs",
-      "import": "./dist/simulator.js"
+      "react-server": {
+        "types": "./dist/simulator/react-server/index.d.ts",
+        "require": "./dist/simulator/react-server.cjs",
+        "import": "./dist/simulator/react-server.js"
+      },
+      "default": {
+        "types": "./dist/simulator/index.d.ts",
+        "require": "./dist/simulator.cjs",
+        "import": "./dist/simulator.js"
+      }
     },
     "./package.json": "./package.json"
   },
@@ -61,11 +68,12 @@
   "dependencies": {
     "@prismicio/simulator": "^0.1.4",
     "@prismicio/types-internal": "^2.2.0",
-    "@slicemachine/plugin-kit": "0.4.37-beta.7",
+    "@slicemachine/plugin-kit": "0.4.37-beta.8",
     "common-tags": "^1.8.2",
     "fp-ts": "^2.13.1",
     "io-ts": "^2.2.20",
     "io-ts-types": "^0.5.19",
+    "lz-string": "1.5.0",
     "monocle-ts": "^2.3.13",
     "newtype-ts": "^0.3.5",
     "node-fetch": "^3.3.1",
@@ -86,6 +94,7 @@
     "eslint-config-prettier": "9.0.0",
     "eslint-plugin-prettier": "5.0.1",
     "eslint-plugin-tsdoc": "0.2.17",
+    "next": "14.1.3",
     "prettier": "3.0.3",
     "prettier-plugin-jsdoc": "1.1.1",
     "react": "18.2.0",

package/src/hooks/project-init.ts

@@ -251,6 +251,10 @@ const createSliceSimulatorPage = async ({
 	helpers,
 	options,
 }: CreateSliceSimulatorPageArgs) => {
+	const isTypeScriptProject = await checkIsTypeScriptProject({
+		helpers,
+		options,
+	});
 	const hasSrcDirectory = await checkHasSrcDirectory({ helpers });
 	const hasAppRouter = await checkHasAppRouter({ helpers });
 
@@ -270,22 +274,69 @@ const createSliceSimulatorPage = async ({
 		return;
 	}
 
-	const contents = source`
-		"use client"
+	let contents;
 
-		import { SliceSimulator } from "@slicemachine/adapter-next/simulator";
-		import { SliceZone } from "@prismicio/react";
+	if (hasAppRouter) {
+		if (isTypeScriptProject) {
+			contents = source`
+				import {
+					SliceSimulator,
+					SliceSimulatorParams,
+					getSlices,
+				} from "@slicemachine/adapter-next/simulator";
+				import { SliceZone } from "@prismicio/react";
+
+				import { components } from "../../slices";
+
+				export default function SliceSimulatorPage({
+					searchParams,
+				}: SliceSimulatorParams) {
+					const slices = getSlices(searchParams.state);
+
+					return (
+						<SliceSimulator>
+							<SliceZone slices={slices} components={components} />
+						</SliceSimulator>
+					);
+				}
+			`;
+		} else {
+			contents = source`
+				import {
+					SliceSimulator,
+					getSlices,
+				} from "@slicemachine/adapter-next/simulator";
+				import { SliceZone } from "@prismicio/react";
+
+				import { components } from "../../slices";
+
+				export default function SliceSimulatorPage({ searchParams }) {
+					const slices = getSlices(searchParams.state);
+
+					return (
+						<SliceSimulator>
+							<SliceZone slices={slices} components={components} />
+						</SliceSimulator>
+					);
+				}
+			`;
+		}
+	} else {
+		contents = source`
+			import { SliceSimulator } from "@slicemachine/adapter-next/simulator";
+			import { SliceZone } from "@prismicio/react";
 
-		import { components } from "${hasAppRouter ? "../.." : ".."}/slices";
+			import { components } from "../slices";
 
-		export default function SliceSimulatorPage() {
-			return (
-				<SliceSimulator
-					sliceZone={(props) => <SliceZone {...props} components={components} />}
-				/>
-			);
-		}
-	`;
+			export default function SliceSimulatorPage() {
+				return (
+					<SliceSimulator
+						sliceZone={(props) => <SliceZone {...props} components={components} />}
+					/>
+				);
+			}
+		`;
+	}
 
 	await writeProjectFile({
 		filename,

package/src/hooks/sliceSimulator-setup-read.ts

@@ -10,6 +10,7 @@ import fetch, { Response } from "node-fetch";
 import { getJSFileExtension } from "../lib/getJSFileExtension";
 
 import type { PluginOptions } from "../types";
+import { checkHasAppRouter } from "../lib/checkHasAppRouter";
 
 const REQUIRED_DEPENDENCIES = ["@prismicio/react"];
 
@@ -79,29 +80,78 @@ const createStep2 = async ({
 	helpers,
 	options,
 }: Args): Promise<SliceSimulatorSetupStep> => {
+	const hasAppRouter = await checkHasAppRouter({ helpers });
+
 	const extension = await getJSFileExtension({ helpers, options, jsx: true });
+
+	if (hasAppRouter) {
+		const fileName = `page.${extension}`;
+		const filePath = helpers.joinPathFromRoot(
+			"app",
+			"slice-simulator",
+			fileName,
+		);
+
+		const fileContents = await helpers.format(
+			source`
+				import {
+					SliceSimulator,
+					SliceSimulatorParams,
+					getSlices,
+				} from "@slicemachine/adapter-next/simulator";
+				import { SliceZone } from "@prismicio/react";
+
+				import { components } from "../../slices";
+
+				export default function SliceSimulatorPage({
+					searchParams,
+				}: SliceSimulatorParams) {
+					const slices = getSlices(searchParams.state);
+
+					return (
+						<SliceSimulator>
+							<SliceZone slices={slices} components={components} />
+						</SliceSimulator>
+					);
+				}
+			`,
+			filePath,
+			{ includeNewlineAtEnd: false },
+		);
+
+		return {
+			title: "Create a page for the simulator",
+			description: `In your \`app\` directory, create a file called \`slice-simulator/${fileName}\` containing this code.`,
+			body: source`
+				In your \`app\` directory, create a file called \`slice-simulator/${fileName}\` and add the following code. This route will be used to simulate and develop your components.
+
+			~~~tsx
+			${fileContents}
+			~~~
+		`,
+		};
+	}
+
 	const fileName = `slice-simulator.${extension}`;
 	const filePath = helpers.joinPathFromRoot("pages", fileName);
 
 	const fileContents = await helpers.format(
 		source`
-			import { SliceSimulator } from "@slicemachine/adapter-next/simulator";
-			import { SliceZone } from "@prismicio/react";
+				import { SliceSimulator } from "@slicemachine/adapter-next/simulator";
+				import { SliceZone } from "@prismicio/react";
 
-			import { components } from "../slices";
+				import { components } from "../slices";
 
-			export default function SliceSimulatorPage() {
-				return (
-					<SliceSimulator
-						sliceZone={(props) => <SliceZone {...props} components={components} />}
-					/>
-				);
-			}
-		`,
+				export default function SliceSimulatorPage() {
+					return (
+						<SliceSimulator
+							sliceZone={(props) => <SliceZone {...props} components={components} />}
+						/>
+					);
+				}
+			`,
 		filePath,
-		{
-			includeNewlineAtEnd: false,
-		},
+		{ includeNewlineAtEnd: false },
 	);
 
 	return {

package/src/simulator/SliceSimulator.tsx

@@ -7,15 +7,12 @@ import {
 	SimulatorManager,
 	SliceSimulatorState,
 	StateEventType,
-	disableEventHandler,
 	getDefaultMessage,
-	getDefaultProps,
 	getDefaultSlices,
-	onClickHandler,
-	simulatorClass,
-	simulatorRootClass,
 } from "@prismicio/simulator/kit";
 
+import { SliceSimulatorWrapper } from "./SliceSimulatorWrapper";
+
 const simulatorManager = new SimulatorManager();
 
 export type SliceSimulatorSliceZoneProps = {
@@ -23,35 +20,50 @@ export type SliceSimulatorSliceZoneProps = {
 };
 
 export type SliceSimulatorProps = {
-	/**
-	 * React component to render simulated Slices.
-	 *
-	 * @example
-	 *
-	 * ```tsx
-	 * import { SliceSimulator } from "@slicemachine/adapter-next/simulator";
-	 * import { SliceZone } from "@prismicio/react";
-	 *
-	 * import { components } from "../slices";
-	 *
-	 * <SliceSimulator
-	 * 	sliceZone={({ slices }) => (
-	 * 		<SliceZone slices={slices} components={components} />
-	 * 	)}
-	 * />;
-	 * ```
-	 */
-	sliceZone: (props: SliceSimulatorSliceZoneProps) => JSX.Element;
 	className?: string;
-} & Omit<BaseSliceSimulatorProps, "state">;
+} & Omit<BaseSliceSimulatorProps, "state"> &
+	(
+		| {
+				/**
+				 * React component to render simulated Slices.
+				 *
+				 * @example
+				 *
+				 * ```tsx
+				 * import { SliceSimulator } from "@slicemachine/adapter-next/simulator";
+				 * import { SliceZone } from "@prismicio/react";
+				 *
+				 * import { components } from "../slices";
+				 *
+				 * <SliceSimulator
+				 * 	sliceZone={({ slices }) => (
+				 * 		<SliceZone slices={slices} components={components} />
+				 * 	)}
+				 * />;
+				 * ```
+				 */
+				sliceZone: (props: SliceSimulatorSliceZoneProps) => JSX.Element;
+		  }
+		| {
+				children: React.ReactNode;
+		  }
+	);
 
+/**
+ * Simulate slices in isolation. The slice simulator enables live slice
+ * development in Slice Machine and live previews in the Page Builder.
+ */
 export const SliceSimulator = ({
-	sliceZone: SliceZoneComp,
 	background,
 	zIndex,
 	className,
+	...restProps
 }: SliceSimulatorProps): JSX.Element => {
-	const defaultProps = getDefaultProps();
+	if (!("sliceZone" in restProps)) {
+		throw new Error(
+			"A sliceZone prop must be provided when <SliceZone> is rendered in a Client Component. Add a sliceZone prop or convert your simulator to a Server Component with the getSlices helper.",
+		);
+	}
 
 	const [slices, setSlices] = React.useState(() => getDefaultSlices());
 	const [message, setMessage] = React.useState(() => getDefaultMessage());
@@ -81,40 +93,17 @@ export const SliceSimulator = ({
 		};
 	}, []);
 
+	const SliceZoneComp = restProps.sliceZone;
+
 	return (
-		<div
-			className={[simulatorClass, className].filter(Boolean).join(" ")}
-			style={{
-				zIndex:
-					typeof zIndex === "undefined"
-						? defaultProps.zIndex
-						: zIndex ?? undefined,
-				position: "fixed",
-				top: 0,
-				left: 0,
-				width: "100%",
-				height: "100vh",
-				overflow: "auto",
-				background:
-					typeof background === "undefined"
-						? defaultProps.background
-						: background ?? undefined,
-			}}
+		<SliceSimulatorWrapper
+			message={message}
+			hasSlices={slices.length > 0}
+			background={background}
+			zIndex={zIndex}
+			className={className}
 		>
-			{message ? (
-				<article dangerouslySetInnerHTML={{ __html: message }} />
-			) : slices.length ? (
-				<div
-					id="root"
-					className={simulatorRootClass}
-					onClickCapture={onClickHandler as unknown as React.MouseEventHandler}
-					onSubmitCapture={
-						disableEventHandler as unknown as React.FormEventHandler
-					}
-				>
-					<SliceZoneComp slices={slices} />
-				</div>
-			) : null}
-		</div>
+			<SliceZoneComp slices={slices} />
+		</SliceSimulatorWrapper>
 	);
 };

package/src/simulator/SliceSimulatorWrapper.tsx

@@ -0,0 +1,68 @@
+import { ReactNode } from "react";
+import {
+	SliceSimulatorProps,
+	disableEventHandler,
+	getDefaultProps,
+	onClickHandler,
+	simulatorClass,
+	simulatorRootClass,
+} from "@prismicio/simulator/kit";
+
+type SliceSimulatorWrapperProps = {
+	children: ReactNode;
+	className?: string;
+	message?: string;
+	hasSlices: boolean;
+} & Omit<SliceSimulatorProps, "state">;
+
+/**
+ * A wrapper for the slice simulator that isolates the given children from the
+ * page's layout.
+ */
+export const SliceSimulatorWrapper = ({
+	className,
+	children,
+	zIndex,
+	background,
+	message,
+	hasSlices,
+}: SliceSimulatorWrapperProps): JSX.Element => {
+	const defaultProps = getDefaultProps();
+
+	return (
+		<div
+			className={[simulatorClass, className].filter(Boolean).join(" ")}
+			style={{
+				zIndex:
+					typeof zIndex === "undefined"
+						? defaultProps.zIndex
+						: zIndex ?? undefined,
+				position: "fixed",
+				top: 0,
+				left: 0,
+				width: "100%",
+				height: "100vh",
+				overflow: "auto",
+				background:
+					typeof background === "undefined"
+						? defaultProps.background
+						: background ?? undefined,
+			}}
+		>
+			{message ? (
+				<article dangerouslySetInnerHTML={{ __html: message }} />
+			) : hasSlices ? (
+				<div
+					id="root"
+					className={simulatorRootClass}
+					onClickCapture={onClickHandler as unknown as React.MouseEventHandler}
+					onSubmitCapture={
+						disableEventHandler as unknown as React.FormEventHandler
+					}
+				>
+					{children}
+				</div>
+			) : null}
+		</div>
+	);
+};

package/src/simulator/getSlices.ts

@@ -0,0 +1,19 @@
+import { StateEvents, StateEventType } from "@prismicio/simulator/kit";
+
+/**
+ * Returns the simulator's slices from the page's `searchParams.state` value.
+ * The `state` value is set by `<SliceSimulator>`.
+ *
+ * **Note**: `getSlices` should only be used in the App Router with a Server
+ * Component.
+ */
+export const getSlices = (
+	state: string | null | undefined,
+): StateEvents[StateEventType.Slices] => {
+	// Prevent tsserver + eslint warnings about unused vars.
+	state;
+
+	throw new Error(
+		"getSlices is designed only for Server Components. Convert your simulator page to a Server Component or remove the function from your Client Component.",
+	);
+};

package/src/simulator/index.ts

@@ -3,3 +3,6 @@ export type {
 	SliceSimulatorProps,
 	SliceSimulatorSliceZoneProps,
 } from "./SliceSimulator";
+
+export { getSlices } from "./getSlices";
+export type { SliceSimulatorParams } from "./types";

package/src/simulator/react-server/SliceSimulator.tsx

@@ -0,0 +1,113 @@
+// This `<SliceSimulator>` is only accessible from Server Components.
+
+"use client";
+
+import * as React from "react";
+
+import {
+	SliceSimulatorProps as BaseSliceSimulatorProps,
+	SimulatorManager,
+	StateEventType,
+	getDefaultMessage,
+} from "@prismicio/simulator/kit";
+import { compressToEncodedURIComponent } from "lz-string";
+
+import { SliceSimulatorWrapper } from "../SliceSimulatorWrapper";
+import { revalidatePath } from "./actions";
+import { getSlices } from "./getSlices";
+
+const STATE_PARAMS_KEY = "state";
+
+const throttle =
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	<TArgs extends [...any]>(fn: (...args: TArgs) => unknown, wait: number) => {
+		let timeoutId: ReturnType<typeof setTimeout>;
+		let lastCallTime = 0;
+
+		return (...args: TArgs) => {
+			clearTimeout(timeoutId);
+
+			const now = Date.now();
+			const timeSinceLastCall = now - lastCallTime;
+			const delayForNextCall = wait - timeSinceLastCall;
+
+			if (delayForNextCall <= 0) {
+				lastCallTime = now;
+				fn(...args);
+			} else {
+				timeoutId = setTimeout(() => {
+					lastCallTime = Date.now();
+					fn(...args);
+				}, delayForNextCall);
+			}
+		};
+	};
+const throttledRevalidatePath = throttle(revalidatePath, 300);
+
+const simulatorManager = new SimulatorManager();
+
+export type SliceSimulatorProps = Omit<BaseSliceSimulatorProps, "state"> & {
+	children: React.ReactNode;
+	className?: string;
+};
+
+export const SliceSimulator = ({
+	children,
+	background,
+	zIndex,
+	className,
+}: SliceSimulatorProps): JSX.Element => {
+	const [message, setMessage] = React.useState(() => getDefaultMessage());
+
+	const state =
+		typeof window !== "undefined"
+			? new URL(window.location.href).searchParams.get(STATE_PARAMS_KEY)
+			: undefined;
+	const hasSlices = getSlices(state).length > 0;
+
+	React.useEffect(() => {
+		simulatorManager.state.on(
+			StateEventType.Slices,
+			(newSlices) => {
+				const url = new URL(window.location.href);
+				url.searchParams.set(
+					STATE_PARAMS_KEY,
+					compressToEncodedURIComponent(JSON.stringify(newSlices)),
+				);
+				window.history.pushState(null, "", url);
+
+				// A 0 ms timeout is needed to prevent a bug
+				// where the path is revalidated before the URL
+				// is updated with the new state.
+				const path = window.location.pathname;
+				setTimeout(() => throttledRevalidatePath(path), 0);
+			},
+			"simulator-slices",
+		);
+		simulatorManager.state.on(
+			StateEventType.Message,
+			(newMessage) => setMessage(newMessage),
+			"simulator-message",
+		);
+
+		simulatorManager.init();
+
+		return () => {
+			simulatorManager.state.off(StateEventType.Slices, "simulator-slices");
+
+			simulatorManager.state.off(StateEventType.Message, "simulator-message");
+		};
+	}, []);
+
+	return (
+		<SliceSimulatorWrapper
+			message={message}
+			hasSlices={hasSlices}
+			background={background}
+			zIndex={zIndex}
+			className={className}
+		>
+			{children}
+		</SliceSimulatorWrapper>
+	);
+};

package/src/simulator/react-server/actions.ts

@@ -0,0 +1,7 @@
+"use server";
+
+import { revalidatePath as baseRevalidatePath } from "next/cache";
+
+export async function revalidatePath(path: string): Promise<void> {
+	baseRevalidatePath(path);
+}

package/src/simulator/react-server/getSlices.ts

@@ -0,0 +1,16 @@
+// This `getSlices` is only accessible from Server Components.
+
+import {
+	getDefaultSlices,
+	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();
+};

package/src/simulator/react-server/index.ts

@@ -0,0 +1,4 @@
+// These exports are only accessible from Server Components.
+
+export { SliceSimulator } from "./SliceSimulator";
+export { getSlices } from "./getSlices";

package/src/simulator/types.ts

@@ -0,0 +1,11 @@
+/**
+ * Parameters provided to the Slice Simulator page.
+ *
+ * **Note**: `SliceSimulatorParams` should only be used in the App Router with a
+ * Server Component.
+ */
+export type SliceSimulatorParams = {
+	searchParams: {
+		state?: string;
+	};
+};