@btst/stack 2.12.2 → 3.0.0-rc.1

package/src/__tests__/i18n-provider.test.tsx

@@ -0,0 +1,99 @@
+// @vitest-environment jsdom
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+	StackProvider,
+	useTranslate,
+	type StackI18nProvider,
+} from "../context";
+
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+let container: HTMLDivElement;
+let root: Root;
+
+beforeEach(() => {
+	container = document.createElement("div");
+	document.body.appendChild(container);
+	root = createRoot(container);
+});
+
+afterEach(async () => {
+	await act(async () => {
+		root.unmount();
+	});
+	container.remove();
+	vi.restoreAllMocks();
+});
+
+async function render(ui: React.ReactElement) {
+	await act(async () => {
+		root.render(ui);
+	});
+}
+
+describe("useTranslate", () => {
+	it("returns the default string when no i18n provider is configured", async () => {
+		let t: ReturnType<typeof useTranslate> | undefined;
+		function Probe() {
+			t = useTranslate();
+			return null;
+		}
+		await render(
+			<StackProvider basePath="/pages">
+				<Probe />
+			</StackProvider>,
+		);
+
+		expect(t!("blog.posts.create", "Create Post")).toBe("Create Post");
+	});
+
+	it("interpolates {{param}} placeholders in the default string", async () => {
+		let t: ReturnType<typeof useTranslate> | undefined;
+		function Probe() {
+			t = useTranslate();
+			return null;
+		}
+		await render(
+			<StackProvider basePath="/pages">
+				<Probe />
+			</StackProvider>,
+		);
+
+		expect(
+			t!("blog.posts.deleted", "Deleted {{title}}", { title: "Hello" }),
+		).toBe("Deleted Hello");
+	});
+
+	it("delegates to the consumer translate function", async () => {
+		const translate = vi.fn(
+			(key: string, defaultValue: string, params?: Record<string, unknown>) =>
+				`[${key}] ${defaultValue} ${params?.title ?? ""}`.trim(),
+		);
+		const i18n: StackI18nProvider = { translate };
+
+		let t: ReturnType<typeof useTranslate> | undefined;
+		function Probe() {
+			t = useTranslate();
+			return null;
+		}
+
+		await render(
+			<StackProvider basePath="/pages" i18n={i18n}>
+				<Probe />
+			</StackProvider>,
+		);
+
+		const result = t!("blog.posts.deleted", "Deleted {{title}}", {
+			title: "Draft",
+		});
+
+		expect(translate).toHaveBeenCalledWith(
+			"blog.posts.deleted",
+			"Deleted {{title}}",
+			{ title: "Draft" },
+		);
+		expect(result).toBe("[blog.posts.deleted] Deleted {{title}} Draft");
+	});
+});

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

@@ -0,0 +1,51 @@
+/**
+ * SSG guard: factory-generated Kanban query keys must stay deep-equal to the
+ * builders used by `prefetchForRoute`. Key drift silently breaks hydration.
+ */
+import { describe, expect, it, vi } from "vitest";
+import { KANBAN_QUERY_KEYS } from "../plugins/kanban/api/query-key-defs";
+import { createKanbanQueryKeys } from "../plugins/kanban/query-keys";
+
+const client = vi.fn() as any;
+
+describe("kanban query keys match SSG prefetch keys", () => {
+	const queries = createKanbanQueryKeys(client);
+
+	it("board list keys match for default params", () => {
+		expect([...queries.boards.list().queryKey]).toEqual([
+			...KANBAN_QUERY_KEYS.boardsList(),
+		]);
+	});
+
+	it("board list keys match for every supported filter", () => {
+		const params = {
+			slug: "roadmap",
+			ownerId: "user-1",
+			organizationId: "org-1",
+			limit: 10,
+			offset: 20,
+		};
+		expect([...queries.boards.list(params).queryKey]).toEqual([
+			...KANBAN_QUERY_KEYS.boardsList(params),
+		]);
+	});
+
+	it("board detail keys match", () => {
+		expect([...queries.boards.detail("board-1").queryKey]).toEqual([
+			...KANBAN_QUERY_KEYS.boardDetail("board-1"),
+		]);
+	});
+
+	it("preserves the previous query-key factory prefixes", () => {
+		expect([...queries.boards._def]).toEqual(["boards"]);
+		expect([...queries.boards.list._def]).toEqual(["boards", "list"]);
+		expect([...queries.boards.detail._def]).toEqual(["boards", "detail"]);
+		expect([...queries.boards.bySlug._def]).toEqual(["boards", "bySlug"]);
+		expect([...queries.boards.bySlug("roadmap").queryKey]).toEqual([
+			"boards",
+			"bySlug",
+			"slug",
+			"roadmap",
+		]);
+	});
+});

package/src/__tests__/list-state.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from "vitest";
+import {
+	parseListStateFromSearchParams,
+	resolveListStateHistoryMode,
+	serializeListStateToSearchParams,
+} from "../shared/list-state";
+
+const schema = {
+	tab: { type: "string" as const, default: "pending" },
+	page: { type: "number" as const, default: 1 },
+	filter: { type: "string" as const, default: "", history: "replace" as const },
+};
+
+describe("parseListStateFromSearchParams", () => {
+	it("returns defaults for an empty query string", () => {
+		expect(
+			parseListStateFromSearchParams("comments-moderation", schema, ""),
+		).toEqual({ tab: "pending", page: 1, filter: "" });
+	});
+
+	it("parses non-default values from URL params", () => {
+		const params = new URLSearchParams("tab=spam&page=3&filter=hello");
+		expect(
+			parseListStateFromSearchParams("comments-moderation", schema, params),
+		).toEqual({ tab: "spam", page: 3, filter: "hello" });
+	});
+
+	it("falls back to defaults for invalid numbers", () => {
+		const params = new URLSearchParams("page=abc");
+		expect(
+			parseListStateFromSearchParams("comments-moderation", schema, params)
+				.page,
+		).toBe(1);
+	});
+});
+
+describe("serializeListStateToSearchParams", () => {
+	it("omits fields equal to their defaults", () => {
+		const params = serializeListStateToSearchParams(
+			"comments-moderation",
+			schema,
+			{ tab: "pending", page: 1, filter: "" },
+		);
+		expect(params.toString()).toBe("");
+	});
+
+	it("serializes only deviating fields", () => {
+		const params = serializeListStateToSearchParams(
+			"comments-moderation",
+			schema,
+			{ tab: "spam", page: 3, filter: "" },
+		);
+		expect(params.toString()).toBe("tab=spam&page=3");
+	});
+
+	it("preserves unrelated params in the base query string", () => {
+		const base = new URLSearchParams("foo=bar");
+		const params = serializeListStateToSearchParams(
+			"comments-moderation",
+			schema,
+			{ tab: "spam", page: 1, filter: "" },
+			base,
+		);
+		expect(params.get("foo")).toBe("bar");
+		expect(params.get("tab")).toBe("spam");
+		expect(params.has("page")).toBe(false);
+	});
+});
+
+describe("resolveListStateHistoryMode", () => {
+	it("defaults to push when no replace fields are updated", () => {
+		expect(resolveListStateHistoryMode(schema, { tab: "spam", page: 2 })).toBe(
+			false,
+		);
+	});
+
+	it("uses replace when a replace-history field is updated", () => {
+		expect(resolveListStateHistoryMode(schema, { filter: "x" })).toBe(true);
+	});
+
+	it("honors an explicit replace option", () => {
+		expect(resolveListStateHistoryMode(schema, { tab: "spam" }, true)).toBe(
+			true,
+		);
+		expect(resolveListStateHistoryMode(schema, { filter: "x" }, false)).toBe(
+			false,
+		);
+	});
+});

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

@@ -0,0 +1,87 @@
+/**
+ * Guard the Media resource declaration against client/server key drift and
+ * preserve the root-vs-all folder wire semantics used by the folder tree.
+ */
+import { describe, expect, it, vi } from "vitest";
+import {
+	MEDIA_QUERY_KEYS,
+	assetListDiscriminator,
+} from "../plugins/media/api/query-key-defs";
+import {
+	createMediaQueryKeys,
+	mediaResources,
+} from "../plugins/media/query-keys";
+import { ROOT_FOLDER_QUERY_VALUE } from "../plugins/media/schemas";
+
+describe("media resource query keys", () => {
+	it("matches the shared asset-list builder and normalizes search", () => {
+		const client = vi.fn() as any;
+		const queries = createMediaQueryKeys(client);
+		const params = { folderId: "photos", query: "  beach  ", limit: 40 };
+
+		expect([...queries.mediaAssets.list(params).queryKey]).toEqual([
+			...MEDIA_QUERY_KEYS.assetsList(params),
+		]);
+		expect(assetListDiscriminator(params).query).toBe("beach");
+	});
+
+	it("uses distinct keys for all folders, root folders, and a parent", () => {
+		const client = vi.fn() as any;
+		const queries = createMediaQueryKeys(client);
+
+		expect([...queries.mediaFolders.list(undefined).queryKey]).toEqual([
+			...MEDIA_QUERY_KEYS.foldersList(undefined),
+		]);
+		expect([...queries.mediaFolders.list(null).queryKey]).toEqual([
+			...MEDIA_QUERY_KEYS.foldersList(null),
+		]);
+		expect(queries.mediaFolders.list(undefined).queryKey).not.toEqual(
+			queries.mediaFolders.list(null).queryKey,
+		);
+		expect([...queries.mediaFolders.list("parent-1").queryKey]).toEqual([
+			"mediaFolders",
+			"list",
+			"parent-1",
+		]);
+	});
+
+	it("sends the root sentinel only for an explicit null parent", async () => {
+		const client = vi.fn().mockResolvedValue({ data: [] }) as any;
+		const queries = createMediaQueryKeys(client);
+
+		await queries.mediaFolders.list(undefined).queryFn();
+		expect(client).toHaveBeenLastCalledWith(
+			"/media/folders",
+			expect.objectContaining({ query: {} }),
+		);
+
+		await queries.mediaFolders.list(null).queryFn();
+		expect(client).toHaveBeenLastCalledWith(
+			"/media/folders",
+			expect.objectContaining({
+				query: { parentId: ROOT_FOLDER_QUERY_VALUE },
+			}),
+		);
+	});
+
+	it("stops infinite pagination after all rows are loaded", () => {
+		const nextPageParam = mediaResources.mediaAssets.queries.list.nextPageParam;
+		const first = { items: new Array(20), total: 25 };
+		const last = { items: new Array(5), total: 25 };
+
+		expect(nextPageParam(first, [first])).toBe(20);
+		expect(nextPageParam(last, [first, last])).toBeUndefined();
+	});
+
+	it("preserves the corrected v3 query-key prefixes", () => {
+		const client = vi.fn() as any;
+		const queries = createMediaQueryKeys(client);
+
+		expect([...queries.mediaAssets._def]).toEqual(["mediaAssets"]);
+		expect([...queries.mediaAssets.list._def]).toEqual(["mediaAssets", "list"]);
+		expect([...queries.mediaFolders.list._def]).toEqual([
+			"mediaFolders",
+			"list",
+		]);
+	});
+});

package/src/__tests__/notify-provider.test.tsx

@@ -0,0 +1,100 @@
+// @vitest-environment jsdom
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { StackProvider, useNotify, type StackNotifyProvider } from "../context";
+
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+const toastSuccess = vi.fn();
+const toastError = vi.fn();
+const toastInfo = vi.fn();
+const toastWarning = vi.fn();
+
+vi.mock("sonner", () => ({
+	toast: {
+		success: (...args: unknown[]) => toastSuccess(...args),
+		error: (...args: unknown[]) => toastError(...args),
+		info: (...args: unknown[]) => toastInfo(...args),
+		warning: (...args: unknown[]) => toastWarning(...args),
+	},
+}));
+
+let container: HTMLDivElement;
+let root: Root;
+
+beforeEach(() => {
+	container = document.createElement("div");
+	document.body.appendChild(container);
+	root = createRoot(container);
+	toastSuccess.mockClear();
+	toastError.mockClear();
+	toastInfo.mockClear();
+	toastWarning.mockClear();
+});
+
+afterEach(async () => {
+	await act(async () => {
+		root.unmount();
+	});
+	container.remove();
+	vi.restoreAllMocks();
+});
+
+async function render(ui: React.ReactElement) {
+	await act(async () => {
+		root.render(ui);
+	});
+}
+
+describe("useNotify", () => {
+	it("uses sonner by default when no notify prop is configured", async () => {
+		let notify: StackNotifyProvider | undefined;
+		function Probe() {
+			notify = useNotify();
+			return null;
+		}
+		await render(
+			<StackProvider basePath="/pages">
+				<Probe />
+			</StackProvider>,
+		);
+
+		notify!.success!("Saved");
+		notify!.error!("Failed", { description: "Try again" });
+
+		expect(toastSuccess).toHaveBeenCalledWith("Saved", undefined);
+		expect(toastError).toHaveBeenCalledWith("Failed", {
+			description: "Try again",
+		});
+	});
+
+	it("routes notifications through a custom provider", async () => {
+		const customSuccess = vi.fn();
+		const customError = vi.fn();
+		let notify: StackNotifyProvider | undefined;
+
+		function Probe() {
+			notify = useNotify();
+			return null;
+		}
+
+		await render(
+			<StackProvider
+				basePath="/pages"
+				notify={{ success: customSuccess, error: customError }}
+			>
+				<Probe />
+			</StackProvider>,
+		);
+
+		notify!.success!("Custom saved");
+		notify!.error!("Custom failed");
+		notify!.info!("Still sonner");
+
+		expect(customSuccess).toHaveBeenCalledWith("Custom saved");
+		expect(customError).toHaveBeenCalledWith("Custom failed");
+		expect(toastInfo).toHaveBeenCalledWith("Still sonner", undefined);
+		expect(toastSuccess).not.toHaveBeenCalled();
+	});
+});

package/src/__tests__/page-component-overrides.test.tsx

@@ -1,47 +1,55 @@
 import { describe, it, expect } from "vitest";
 import { defineClientPlugin } from "../plugins/client";
-import type { ComponentType } from "react";
-import { createRoute } from "@btst/yar";
+import type { ComponentType, ReactElement } from "react";
+import { defineRoute, defineRoutes } from "@btst/yar";
 
 /**
  * Default page components used by the mock plugin factory.
  * These stand in for the real plugin page components (e.g. HomePageComponent).
  */
-const DefaultListComponent: ComponentType = () => <div>Default List</div>;
+const DefaultListComponent = () => <div>Default List</div>;
 const DefaultDetailComponent: ComponentType<{ id: string }> = ({ id }) => (
 	<div>Default Detail {id}</div>
 );
 
+/**
+ * Renders a bound page component (context injected as props) and returns the
+ * produced element for inspection, without needing a DOM.
+ */
+function renderBound(
+	Component: ComponentType<Record<string, unknown>> | undefined,
+): ReactElement<Record<string, unknown>> | null {
+	if (!Component) return null;
+	return (
+		Component as (
+			props: Record<string, unknown>,
+		) => ReactElement<Record<string, unknown>>
+	)({});
+}
+
 /**
  * Lightweight mock plugin factory that mirrors the real plugin pattern:
- * - Accepts a config with an optional `pageComponents` field
- * - Falls back to built-in components when no override is provided
- * - For param routes, extracts the override before the handler closure
+ * - Declares routes with defineRoute
+ * - Applies the optional `pageComponents` config via defineRoutes' pages option
  */
 function createTestPlugin(config: {
 	pageComponents?: {
 		list?: ComponentType;
-		detail?: ComponentType<{ id: string }>;
+		detail?: ComponentType<{ params: { id: string } }>;
 	};
 }) {
 	return defineClientPlugin({
 		name: "test",
-		routes: () => ({
-			list: createRoute("/items", () => {
-				const CustomList = config.pageComponents?.list;
-				return {
-					PageComponent: CustomList ?? DefaultListComponent,
-				};
-			}),
-			detail: createRoute("/items/:id", ({ params }) => {
-				const CustomDetail = config.pageComponents?.detail;
-				return {
-					PageComponent: CustomDetail
-						? () => <CustomDetail id={params.id} />
-						: () => <DefaultDetailComponent id={params.id} />,
-				};
-			}),
-		}),
+		routes: () =>
+			defineRoutes(
+				{
+					list: defineRoute("/items", { page: DefaultListComponent }),
+					detail: defineRoute("/items/:id", {
+						page: ({ params }) => <DefaultDetailComponent id={params.id} />,
+					}),
+				},
+				{ pages: config.pageComponents },
+			),
 	});
 }
 
@@ -52,7 +60,8 @@ describe("pageComponents overrides", () => {
 			const routes = plugin.routes();
 			const routeData = routes.list();
 
-			expect(routeData.PageComponent).toBe(DefaultListComponent);
+			const element = renderBound(routeData.PageComponent);
+			expect(element?.type).toBe(DefaultListComponent);
 		});
 
 		it("uses the default component wrapper for a param route", () => {
@@ -60,14 +69,12 @@ describe("pageComponents overrides", () => {
 			const routes = plugin.routes();
 			const routeData = routes.detail({ params: { id: "42" } });
 
-			// Should be an inline wrapper, not the custom component
 			expect(routeData.PageComponent).toBeDefined();
 			expect(typeof routeData.PageComponent).toBe("function");
-			// Verify it is NOT the custom component (no override was given)
-			const CustomDetail: ComponentType<{ id: string }> = () => (
-				<div>Custom</div>
-			);
-			expect(routeData.PageComponent).not.toBe(CustomDetail);
+
+			// The default page receives the route context and forwards params.id
+			const element = renderBound(routeData.PageComponent);
+			expect(element?.props.params).toEqual({ id: "42" });
 		});
 	});
 
@@ -81,8 +88,9 @@ describe("pageComponents overrides", () => {
 			const routes = plugin.routes();
 			const routeData = routes.list();
 
-			expect(routeData.PageComponent).toBe(CustomList);
-			expect(routeData.PageComponent).not.toBe(DefaultListComponent);
+			const element = renderBound(routeData.PageComponent);
+			expect(element?.type).toBe(CustomList);
+			expect(element?.type).not.toBe(DefaultListComponent);
 		});
 
 		it("leaves other routes using their defaults when only one is overridden", () => {
@@ -94,19 +102,21 @@ describe("pageComponents overrides", () => {
 			const routes = plugin.routes();
 
 			// list uses custom
-			expect(routes.list().PageComponent).toBe(CustomList);
+			const listElement = renderBound(routes.list().PageComponent);
+			expect(listElement?.type).toBe(CustomList);
 
-			// detail still uses a wrapper (no override)
+			// detail still uses its default wrapper (no override)
 			const detailData = routes.detail({ params: { id: "1" } });
-			expect(detailData.PageComponent).not.toBe(CustomList);
+			const detailElement = renderBound(detailData.PageComponent);
+			expect(detailElement?.type).not.toBe(CustomList);
 		});
 	});
 
 	describe("custom component replaces default (param route)", () => {
-		it("uses the override wrapper for a param route", () => {
-			const CustomDetail: ComponentType<{ id: string }> = ({ id }) => (
-				<div>Custom Detail {id}</div>
-			);
+		it("passes the route context to the override as props", () => {
+			const CustomDetail: ComponentType<{ params: { id: string } }> = ({
+				params,
+			}) => <div>Custom Detail {params.id}</div>;
 
 			const plugin = createTestPlugin({
 				pageComponents: { detail: CustomDetail },
@@ -114,34 +124,30 @@ describe("pageComponents overrides", () => {
 			const routes = plugin.routes();
 			const routeData = routes.detail({ params: { id: "42" } });
 
-			// Should be an inline wrapper (not the raw CustomDetail directly)
-			expect(routeData.PageComponent).toBeDefined();
-			expect(typeof routeData.PageComponent).toBe("function");
-			// Should NOT be the default
-			expect(routeData.PageComponent).not.toBe(DefaultDetailComponent);
+			const element = renderBound(routeData.PageComponent);
+			expect(element?.type).toBe(CustomDetail);
+			expect(element?.props.params).toEqual({ id: "42" });
 		});
 
 		it("produces a different PageComponent than when no override is given", () => {
-			const CustomDetail: ComponentType<{ id: string }> = ({ id }) => (
-				<div>Custom Detail {id}</div>
-			);
+			const CustomDetail: ComponentType<{ params: { id: string } }> = ({
+				params,
+			}) => <div>Custom Detail {params.id}</div>;
 
 			const defaultPlugin = createTestPlugin({});
 			const overridePlugin = createTestPlugin({
 				pageComponents: { detail: CustomDetail },
 			});
 
-			const defaultRouteData = defaultPlugin
-				.routes()
-				.detail({ params: { id: "1" } });
-			const overrideRouteData = overridePlugin
-				.routes()
-				.detail({ params: { id: "1" } });
-
-			// The wrapped component should be a different function reference
-			expect(overrideRouteData.PageComponent).not.toBe(
-				defaultRouteData.PageComponent,
+			const defaultElement = renderBound(
+				defaultPlugin.routes().detail({ params: { id: "1" } }).PageComponent,
+			);
+			const overrideElement = renderBound(
+				overridePlugin.routes().detail({ params: { id: "1" } }).PageComponent,
 			);
+
+			expect(overrideElement?.type).toBe(CustomDetail);
+			expect(defaultElement?.type).not.toBe(CustomDetail);
 		});
 	});
 });