@btst/stack 5.0.0 → 5.2.0

package/src/__tests__/cms-query-keys.test.ts

@@ -54,6 +54,63 @@ describe("cms query keys match SSG prefetch keys", () => {
 		]);
 	});
 
+	it("normalizes equivalent selections across read identities and preserves prefetch parity", () => {
+		const fields = ["title", "name.with.dot", "title"];
+		const keys = [
+			(selection?: readonly string[]) =>
+				queries.cmsContent.options({
+					typeSlug: "post",
+					view: "content",
+					fields: selection,
+				}).queryKey,
+			(selection?: readonly string[]) =>
+				queries.cmsContent.list({
+					typeSlug: "post",
+					view: "content",
+					fields: selection,
+				}).queryKey,
+			(selection?: readonly string[]) =>
+				queries.cmsContent.detail("post", "id", {
+					view: "content",
+					fields: selection,
+				}).queryKey,
+			(selection?: readonly string[]) =>
+				queries.cmsContent.bySlug("post", "slug", {
+					view: "content",
+					fields: selection,
+				}).queryKey,
+			(selection?: readonly string[]) =>
+				queries.cmsContent.byRelation({
+					typeSlug: "post",
+					field: "authorId",
+					targetId: "author",
+					view: "content",
+					fields: selection,
+				}).queryKey,
+			(selection?: readonly string[]) =>
+				queries.cmsTypes.inverseRelationItems({
+					slug: "author",
+					sourceType: "post",
+					itemId: "author",
+					fieldName: "authorId",
+					view: "content",
+					fields: selection,
+				}).queryKey,
+		];
+		for (const key of keys) {
+			expect(key(fields)).toEqual(key(["name.with.dot", "title"]));
+			expect(key(fields)).not.toEqual(key(["title"]));
+			expect(key(fields)).not.toEqual(key());
+		}
+		expect(fields).toEqual(["title", "name.with.dot", "title"]);
+		expect(keys[1]!(fields)).toEqual(
+			CMS_QUERY_KEYS.contentList({ typeSlug: "post", view: "content", fields }),
+		);
+		expect(keys[2]!(fields)).toEqual(
+			CMS_QUERY_KEYS.contentDetail("post", "id", { view: "content", fields }),
+		);
+	});
+
 	it("exposes the same _def prefixes as the previous factory", () => {
 		expect([...queries.cmsTypes._def]).toEqual(["cmsTypes"]);
 		expect([...queries.cmsTypes.list._def]).toEqual(["cmsTypes", "list"]);

package/src/__tests__/route-render-lifecycle.test.tsx

@@ -0,0 +1,242 @@
+// @vitest-environment jsdom
+import { act, lazy, StrictMode, Suspense } from "react";
+import { createRoot } from "react-dom/client";
+import { expect, it, vi } from "vitest";
+import { defineRoute, defineRoutes } from "@btst/yar";
+import { QueryClientProvider } from "@tanstack/react-query";
+import { ComposedRoute, RouteRenderer } from "../client/components/compose";
+import { RouteLifecycle } from "../client/components/route-lifecycle";
+import { StackProvider } from "../context";
+import { createNextPage } from "../next/page";
+import { defineClientPlugin } from "../plugins/client";
+import { createTestClientStack } from "./client-stack-test-utils";
+
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+function observerStack(onRouteRender: (context: { path: string }) => void) {
+	return createTestClientStack({
+		observer: defineClientPlugin({
+			id: "observer",
+			resolve: () => ({
+				routes: () =>
+					defineRoutes({
+						first: defineRoute("/first", { page: () => <div>First page</div> }),
+						second: defineRoute("/second", {
+							page: () => <div>Second page</div>,
+						}),
+					}),
+				hooks: { onRouteRender },
+			}),
+		}),
+	});
+}
+
+it("observes plain RouteRenderer pages and navigation once, including StrictMode and rerenders", async () => {
+	const onRouteRender = vi.fn();
+	const stack = observerStack(onRouteRender);
+	const container = document.createElement("div");
+	const root = createRoot(container);
+	const render = (path: string) => (
+		<StrictMode>
+			<StackProvider stack={stack}>
+				<RouteRenderer router={stack.router} path={path} onError={() => {}} />
+			</StackProvider>
+		</StrictMode>
+	);
+	try {
+		await act(async () => root.render(render("/first")));
+		await act(async () => root.render(render("/first")));
+		await act(async () => root.render(render("/second")));
+		await act(async () => root.render(render("/first")));
+		expect(container.textContent).toBe("First page");
+		expect(onRouteRender.mock.calls).toEqual([
+			[{ path: "/first" }],
+			[{ path: "/second" }],
+			[{ path: "/first" }],
+		]);
+	} finally {
+		await act(async () => root.unmount());
+		stack.provider.queryClient.clear();
+	}
+});
+
+it("observes plain framework pages that do not use ComposedRoute", async () => {
+	const onRouteRender = vi.fn();
+	const stack = observerStack(onRouteRender);
+	const page = createNextPage({
+		getStackClient: () => stack,
+		getQueryClient: () => stack.provider.queryClient,
+	});
+	const element = await page.Page({
+		params: Promise.resolve({ all: ["first"] }),
+	});
+	const container = document.createElement("div");
+	const root = createRoot(container);
+	try {
+		await act(async () =>
+			root.render(
+				<QueryClientProvider client={stack.provider.queryClient}>
+					<StackProvider stack={stack}>{element}</StackProvider>
+				</QueryClientProvider>,
+			),
+		);
+		expect(container.textContent).toBe("First page");
+		expect(onRouteRender).toHaveBeenCalledExactlyOnceWith({ path: "/first" });
+	} finally {
+		await act(async () => root.unmount());
+		stack.provider.queryClient.clear();
+	}
+});
+
+it("observes standalone ComposedRoute pages used by static routes without duplicate nested notifications", async () => {
+	const onRouteRender = vi.fn();
+	const stack = observerStack(onRouteRender);
+	const container = document.createElement("div");
+	const root = createRoot(container);
+	const Page = () => (
+		<RouteRenderer router={stack.router} path="/first" onError={() => {}} />
+	);
+	const render = () => (
+		<StrictMode>
+			<StackProvider stack={stack}>
+				<ComposedRoute
+					path="/static"
+					PageComponent={Page}
+					LoadingComponent={() => null}
+					onError={() => {}}
+				/>
+			</StackProvider>
+		</StrictMode>
+	);
+	try {
+		await act(async () => root.render(render()));
+		await act(async () => root.render(render()));
+		expect(container.textContent).toBe("First page");
+		expect(onRouteRender).toHaveBeenCalledExactlyOnceWith({ path: "/static" });
+	} finally {
+		await act(async () => root.unmount());
+		stack.provider.queryClient.clear();
+	}
+});
+
+it("waits for a suspended root to commit before observing its route", async () => {
+	const onRouteRender = vi.fn();
+	const stack = observerStack(onRouteRender);
+	const container = document.createElement("div");
+	const root = createRoot(container);
+	let resolve!: (value: { default: () => React.ReactNode }) => void;
+	const Page = lazy(
+		() =>
+			new Promise<{ default: () => React.ReactNode }>((done) => {
+				resolve = done;
+			}),
+	);
+	try {
+		await act(async () =>
+			root.render(
+				<StackProvider stack={stack}>
+					<Suspense fallback={<div>Loading</div>}>
+						<RouteLifecycle path="/pending">
+							<Page />
+						</RouteLifecycle>
+					</Suspense>
+				</StackProvider>,
+			),
+		);
+		expect(container.textContent).toBe("Loading");
+		expect(onRouteRender).not.toHaveBeenCalled();
+		await act(async () => resolve({ default: () => <div>Ready</div> }));
+		expect(container.textContent).toBe("Ready");
+		expect(onRouteRender).toHaveBeenCalledExactlyOnceWith({ path: "/pending" });
+	} finally {
+		await act(async () => root.unmount());
+		stack.provider.queryClient.clear();
+	}
+});
+
+it("does not double count delayed nested ComposedRoute or RouteRenderer commits", async () => {
+	const onRouteRender = vi.fn();
+	const stack = observerStack(onRouteRender);
+	const container = document.createElement("div");
+	const root = createRoot(container);
+	let resolve!: (value: { default: () => React.ReactNode }) => void;
+	const Page = lazy(
+		() =>
+			new Promise<{ default: () => React.ReactNode }>((done) => {
+				resolve = done;
+			}),
+	);
+	try {
+		await act(async () =>
+			root.render(
+				<StackProvider stack={stack}>
+					<RouteLifecycle path="/outer">
+						<ComposedRoute
+							path="/inner"
+							PageComponent={Page}
+							LoadingComponent={() => <div>Loading</div>}
+							onError={() => {}}
+						/>
+					</RouteLifecycle>
+				</StackProvider>,
+			),
+		);
+		expect(container.textContent).toBe("Loading");
+		expect(onRouteRender).toHaveBeenCalledExactlyOnceWith({ path: "/outer" });
+		await act(async () =>
+			resolve({
+				default: () => (
+					<RouteRenderer
+						router={stack.router}
+						path="/first"
+						onError={() => {}}
+					/>
+				),
+			}),
+		);
+		expect(container.textContent).toBe("First page");
+		expect(onRouteRender).toHaveBeenCalledOnce();
+	} finally {
+		await act(async () => root.unmount());
+		stack.provider.queryClient.clear();
+	}
+});
+
+it("keeps failing observers from interrupting other observers or the page", async () => {
+	const onRouteRender = vi.fn();
+	const observer = (id: string, callback: () => void | Promise<void>) =>
+		defineClientPlugin({
+			id,
+			resolve: () => ({
+				routes: () => ({}),
+				hooks: { onRouteRender: callback },
+			}),
+		});
+	const stack = createTestClientStack({
+		throwing: observer("throwing", () => {
+			throw new Error("observer failed");
+		}),
+		rejecting: observer("rejecting", () =>
+			Promise.reject(new Error("offline")),
+		),
+		working: observer("working", onRouteRender),
+	});
+	const container = document.createElement("div");
+	const root = createRoot(container);
+	try {
+		await act(async () =>
+			root.render(
+				<StackProvider stack={stack}>
+					<RouteLifecycle path="/working">
+						<div>Page</div>
+					</RouteLifecycle>
+				</StackProvider>,
+			),
+		);
+		expect(container.textContent).toBe("Page");
+		expect(onRouteRender).toHaveBeenCalledExactlyOnceWith({ path: "/working" });
+	} finally {
+		await act(async () => root.unmount());
+		stack.provider.queryClient.clear();
+	}
+});

package/src/client/components/compose.tsx

@@ -11,6 +11,7 @@ import {
 import { useStackOrNull } from "../../context/provider";
 import type { PermissionRequest } from "../../authorization";
 import { ErrorBoundary } from "./error-boundary";
+import { RouteLifecycle } from "./route-lifecycle";
 
 type RoutePermission = PermissionRequest;
 
@@ -56,16 +57,18 @@ export function RouteRenderer({
 	const route = React.useMemo(() => router.getRoute(path), [router, path]);
 
 	return (
-		<ComposedRoute
-			path={path}
-			PageComponent={route?.PageComponent}
-			ErrorComponent={route?.ErrorComponent}
-			LoadingComponent={route?.LoadingComponent}
-			onNotFound={onNotFound}
-			NotFoundComponent={NotFoundComponent}
-			onError={onError}
-			props={props}
-		/>
+		<RouteLifecycle path={path}>
+			<ComposedRoute
+				path={path}
+				PageComponent={route?.PageComponent}
+				ErrorComponent={route?.ErrorComponent}
+				LoadingComponent={route?.LoadingComponent}
+				onNotFound={onNotFound}
+				NotFoundComponent={NotFoundComponent}
+				onError={onError}
+				props={props}
+			/>
+		</RouteLifecycle>
 	);
 }
 
@@ -272,15 +275,20 @@ export function ComposedRoute({
 	permission?: RoutePermission;
 }) {
 	if (PageComponent) {
+		const page = (
+			<RouteLifecycle path={path}>
+				<PageComponent {...props} />
+			</RouteLifecycle>
+		);
 		const content = permission ? (
 			<PermissionRouteAccess
 				permission={permission}
 				LoadingComponent={LoadingComponent}
 			>
-				<PageComponent {...props} />
+				{page}
 			</PermissionRouteAccess>
 		) : (
-			<PageComponent {...props} />
+			page
 		);
 		// Always provide the same fallback on server and client — using
 		// `typeof window !== "undefined"` here would produce a different JSX tree

package/src/client/components/route-lifecycle.tsx

@@ -0,0 +1,45 @@
+"use client";
+
+import {
+	createContext,
+	useContext,
+	useEffect,
+	useRef,
+	type ReactNode,
+} from "react";
+import { useStackOrNull } from "../../context/provider";
+
+const RouteLifecycleOwner = createContext(false);
+
+/** One committed page render owns lifecycle notifications, including nested route renderers. */
+export function RouteLifecycle({
+	path,
+	children,
+}: {
+	path: string;
+	children: ReactNode;
+}) {
+	const parentOwnsLifecycle = useContext(RouteLifecycleOwner);
+	const context = useStackOrNull()?.clientStackContext;
+	const observedPath = useRef<string | undefined>(undefined);
+	useEffect(() => {
+		if (parentOwnsLifecycle || !context || observedPath.current === path)
+			return;
+		observedPath.current = path;
+		for (const plugin of Object.values(context.plugins)) {
+			if (!plugin.hooks?.onRouteRender) continue;
+			try {
+				void Promise.resolve(plugin.hooks.onRouteRender({ path })).catch(
+					() => {},
+				);
+			} catch {
+				// Observers must not prevent a page from rendering.
+			}
+		}
+	}, [context, path, parentOwnsLifecycle]);
+	return (
+		<RouteLifecycleOwner.Provider value>
+			{children}
+		</RouteLifecycleOwner.Provider>
+	);
+}

package/src/next/page.tsx

@@ -3,6 +3,7 @@ import type { DehydrateOptions, QueryClient } from "@tanstack/react-query";
 import type { Metadata } from "next";
 import { notFound as nextNotFound } from "next/navigation";
 import type { ReactNode } from "react";
+import { RouteLifecycle } from "../client/components/route-lifecycle";
 import { metaElementsToObject } from "../client/meta-utils";
 import { normalizePath } from "../client/path-utils";
 import {
@@ -94,7 +95,13 @@ export function createNextPage(options: CreateNextPageOptions) {
 			await route.loader();
 		}
 
-		const page = route?.PageComponent ? <route.PageComponent /> : notFound();
+		const page = route?.PageComponent ? (
+			<RouteLifecycle path={path}>
+				<route.PageComponent />
+			</RouteLifecycle>
+		) : (
+			notFound()
+		);
 
 		return (
 			<HydrationBoundary state={dehydrate(queryClient, dehydrateOptions)}>