@btst/stack 2.12.2 → 3.0.0-rc.1

package/src/__tests__/resource-use-form.test.tsx

@@ -0,0 +1,346 @@
+// @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 { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { StackProvider } from "../context";
+import type { ResourcesDeclaration } from "../plugins/client";
+import { createResource } from "../plugins/client/hooks";
+import type { ResourceFormResult } from "../plugins/client/hooks";
+
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+interface Item {
+	id: string;
+	slug: string;
+	name: string;
+}
+
+interface FormValues {
+	name: string;
+}
+
+const resources = {
+	items: {
+		queries: {
+			detail: {
+				path: "/items",
+				query: (slug: string) => ({ slug, limit: 1 }),
+				key: (slug: string) => [slug],
+				select: (data: any): Item | null => data?.items?.[0] ?? null,
+				skip: (slug: string) => !slug,
+			},
+		},
+		mutations: {
+			create: {
+				path: "@post/items",
+				method: "POST" as const,
+				input: (vars: { name: string }) => ({ body: vars }),
+				select: (data: any) => data as Item | null,
+				invalidates: ["items"],
+			},
+			update: {
+				path: "@put/items/:id",
+				method: "PUT" as const,
+				input: (vars: { id: string; data: { name: string } }) => ({
+					params: { id: vars.id },
+					body: vars.data,
+				}),
+				select: (data: any) => data as Item | null,
+				invalidates: ["items"],
+			},
+		},
+	},
+} satisfies ResourcesDeclaration;
+
+const items = createResource({ plugin: "test-plugin", resources });
+
+type FormHookConfig = Parameters<typeof items.items.useForm<FormValues>>[0];
+
+describe("resource useForm", () => {
+	let container: HTMLDivElement;
+	let root: Root;
+	let queryClient: QueryClient;
+	let navigate: ReturnType<typeof vi.fn>;
+	let refresh: ReturnType<typeof vi.fn>;
+	let notifySuccess: ReturnType<typeof vi.fn>;
+	let notifyError: ReturnType<typeof vi.fn>;
+	let fetchMock: ReturnType<typeof vi.spyOn>;
+
+	beforeEach(() => {
+		container = document.createElement("div");
+		document.body.appendChild(container);
+		root = createRoot(container);
+		queryClient = new QueryClient();
+		navigate = vi.fn();
+		refresh = vi.fn();
+		notifySuccess = vi.fn();
+		notifyError = vi.fn();
+		fetchMock = vi.spyOn(globalThis, "fetch" as any);
+	});
+
+	afterEach(async () => {
+		await act(async () => {
+			root.unmount();
+		});
+		container.remove();
+		vi.restoreAllMocks();
+	});
+
+	function jsonResponse(body: unknown, status = 200) {
+		return new Response(JSON.stringify(body), {
+			status,
+			headers: { "content-type": "application/json" },
+		});
+	}
+
+	async function renderForm(
+		config: FormHookConfig,
+		onCapture: (form: ResourceFormResult<FormValues, Item | null>) => void,
+	) {
+		function Probe() {
+			const form = items.items.useForm<FormValues>(config);
+			onCapture(form as ResourceFormResult<FormValues, Item | null>);
+			return null;
+		}
+		await act(async () => {
+			root.render(
+				<StackProvider
+					basePath="/pages"
+					api={{ baseURL: "http://test.local", basePath: "/api/data" }}
+					router={{ navigate, refresh }}
+					notify={{ success: notifySuccess, error: notifyError }}
+				>
+					<QueryClientProvider client={queryClient}>
+						<Probe />
+					</QueryClientProvider>
+				</StackProvider>,
+			);
+		});
+	}
+
+	async function waitFor(check: () => boolean, timeout = 3000) {
+		const start = Date.now();
+		while (!check()) {
+			if (Date.now() - start > timeout) {
+				throw new Error("waitFor timed out");
+			}
+			await act(async () => {
+				await new Promise((resolve) => setTimeout(resolve, 10));
+			});
+		}
+	}
+
+	it("create: submits the create mutation, notifies and redirects", async () => {
+		const created: Item = { id: "1", slug: "one", name: "One" };
+		fetchMock.mockResolvedValue(jsonResponse(created));
+
+		let form!: ResourceFormResult<FormValues, Item | null>;
+		await renderForm(
+			{
+				action: "create",
+				successMessage: "Item saved",
+				redirect: (result) => `/items/${(result as Item).slug}`,
+			},
+			(value) => {
+				form = value;
+			},
+		);
+
+		expect(form.record).toBeNull();
+		expect(form.isLoadingRecord).toBe(false);
+
+		let result: unknown;
+		await act(async () => {
+			result = await form.submit({ name: "One" });
+		});
+
+		expect(result).toEqual(created);
+		const [url, init] = fetchMock.mock.calls[0] as [unknown, RequestInit];
+		expect(String(url)).toContain("/api/data/items");
+		expect(init.method).toBe("POST");
+		expect(notifySuccess).toHaveBeenCalledWith("Item saved");
+		expect(navigate).toHaveBeenCalledWith("/items/one");
+		expect(refresh).toHaveBeenCalledTimes(1);
+		expect(form.error).toBeNull();
+		expect(form.fieldErrors).toEqual({});
+	});
+
+	it("edit: fetches the record, derives defaults and submits the update mutation", async () => {
+		const existing: Item = { id: "9", slug: "nine", name: "Nine" };
+		fetchMock.mockImplementation(async (input: any, init?: any) => {
+			void input;
+			const method = (init as RequestInit | undefined)?.method;
+			if (!method || method === "GET") {
+				return jsonResponse({ items: [existing] });
+			}
+			return jsonResponse({ ...existing, name: "Nine v2" });
+		});
+
+		let form!: ResourceFormResult<FormValues, Item | null>;
+		await renderForm(
+			{
+				action: "edit",
+				id: "nine",
+				defaults: (record) => ({ name: (record as Item | null)?.name ?? "" }),
+				toUpdateVars: (values, record) => ({
+					id: (record as Item).id,
+					data: values,
+				}),
+				successMessage: "Item updated",
+			},
+			(value) => {
+				form = value;
+			},
+		);
+
+		await waitFor(() => form.record !== null);
+		expect(form.record).toEqual(existing);
+		expect(form.defaultValues).toEqual({ name: "Nine" });
+
+		await act(async () => {
+			await form.submit({ name: "Nine v2" });
+		});
+
+		const putCall = fetchMock.mock.calls.find(
+			(call) => (call[1] as RequestInit | undefined)?.method === "PUT",
+		);
+		expect(putCall).toBeDefined();
+		expect(String(putCall?.[0])).toContain("/api/data/items/9");
+		expect(notifySuccess).toHaveBeenCalledWith("Item updated");
+	});
+
+	it("edit: uses an externally supplied record without fetching", async () => {
+		const external: Item = { id: "5", slug: "five", name: "Five" };
+
+		let form!: ResourceFormResult<FormValues, Item | null>;
+		await renderForm(
+			{
+				action: "edit",
+				record: external,
+				defaults: (record) => ({ name: (record as Item | null)?.name ?? "" }),
+			},
+			(value) => {
+				form = value;
+			},
+		);
+
+		expect(form.record).toEqual(external);
+		expect(form.defaultValues).toEqual({ name: "Five" });
+		expect(fetchMock).not.toHaveBeenCalled();
+	});
+
+	it("maps server validation issues onto fieldErrors without a toast", async () => {
+		fetchMock.mockResolvedValue(
+			jsonResponse(
+				{
+					message: "[body.name] Name is required",
+					code: "VALIDATION_ERROR",
+					issues: [{ path: ["name"], message: "Name is required" }],
+				},
+				400,
+			),
+		);
+
+		let form!: ResourceFormResult<FormValues, Item | null>;
+		await renderForm(
+			{
+				action: "create",
+				successMessage: "saved",
+				errorMessage: "Failed to save",
+			},
+			(value) => {
+				form = value;
+			},
+		);
+
+		let result: unknown = "sentinel";
+		await act(async () => {
+			result = await form.submit({ name: "" });
+		});
+
+		expect(result).toBeUndefined();
+		expect(form.fieldErrors).toEqual({ name: "Name is required" });
+		expect(form.error?.statusCode).toBe(400);
+		// Field-level failures do not produce a generic toast
+		expect(notifyError).not.toHaveBeenCalled();
+		expect(notifySuccess).not.toHaveBeenCalled();
+		expect(navigate).not.toHaveBeenCalled();
+	});
+
+	it("notifies errorMessage for non-field errors", async () => {
+		fetchMock.mockResolvedValue(
+			jsonResponse({ message: "Internal error" }, 500),
+		);
+
+		let form!: ResourceFormResult<FormValues, Item | null>;
+		await renderForm(
+			{
+				action: "create",
+				errorMessage: (error) => `Save failed: ${error.message}`,
+			},
+			(value) => {
+				form = value;
+			},
+		);
+
+		await act(async () => {
+			await form.submit({ name: "x" });
+		});
+
+		expect(form.error?.message).toBe("Internal error");
+		expect(form.fieldErrors).toEqual({});
+		expect(notifyError).toHaveBeenCalledWith("Save failed: Internal error");
+	});
+
+	it("clearErrors resets the error state", async () => {
+		fetchMock.mockResolvedValue(
+			jsonResponse(
+				{
+					message: "invalid",
+					issues: [{ path: ["name"], message: "Bad" }],
+				},
+				400,
+			),
+		);
+
+		let form!: ResourceFormResult<FormValues, Item | null>;
+		await renderForm({ action: "create" }, (value) => {
+			form = value;
+		});
+
+		await act(async () => {
+			await form.submit({ name: "" });
+		});
+		expect(form.fieldErrors).toEqual({ name: "Bad" });
+
+		await act(async () => {
+			form.clearErrors();
+		});
+		expect(form.error).toBeNull();
+		expect(form.fieldErrors).toEqual({});
+	});
+
+	it("skips navigation when redirect resolves falsy", async () => {
+		fetchMock.mockResolvedValue(
+			jsonResponse({ id: "1", slug: "one", name: "One" }),
+		);
+
+		let form!: ResourceFormResult<FormValues, Item | null>;
+		await renderForm(
+			{
+				action: "create",
+				redirect: () => false,
+			},
+			(value) => {
+				form = value;
+			},
+		);
+
+		await act(async () => {
+			await form.submit({ name: "One" });
+		});
+
+		expect(navigate).not.toHaveBeenCalled();
+	});
+});

package/src/__tests__/resource-use-select.test.tsx

@@ -0,0 +1,243 @@
+// @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 { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { StackProvider } from "../context";
+import type { ResourcesDeclaration } from "../plugins/client";
+import { createResource } from "../plugins/client/hooks";
+import type { ResourceSelectResult } from "../plugins/client/hooks";
+
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+interface Tag {
+	id: string;
+	name: string;
+}
+
+const resources = {
+	tags: {
+		queries: {
+			list: {
+				path: "/tags",
+				query: (search?: string) => ({ q: search || undefined }),
+				key: (search?: string) => [{ q: search || undefined }],
+				select: (data: any): Tag[] => data ?? [],
+			},
+			detail: {
+				path: "/tags/one",
+				query: (id: string) => ({ id }),
+				key: (id: string) => [id],
+				select: (data: any): Tag | null => data ?? null,
+			},
+		},
+	},
+} satisfies ResourcesDeclaration;
+
+const tags = createResource({ plugin: "test-plugin", resources });
+
+const ALL_TAGS: Tag[] = [
+	{ id: "1", name: "alpha" },
+	{ id: "2", name: "beta" },
+	{ id: "3", name: "kanban" },
+];
+
+describe("resource useSelect", () => {
+	let container: HTMLDivElement;
+	let root: Root;
+	let queryClient: QueryClient;
+	let fetchMock: ReturnType<typeof vi.spyOn>;
+
+	beforeEach(() => {
+		container = document.createElement("div");
+		document.body.appendChild(container);
+		root = createRoot(container);
+		queryClient = new QueryClient();
+		fetchMock = vi.spyOn(globalThis, "fetch" as any);
+		fetchMock.mockImplementation(async (input: any) => {
+			const url = new URL(String(input));
+			if (url.pathname.endsWith("/tags/one")) {
+				const id = url.searchParams.get("id");
+				const tag = id === "42" ? { id: "42", name: "preloaded" } : null;
+				return jsonResponse(tag);
+			}
+			const q = url.searchParams.get("q");
+			const filtered = q
+				? ALL_TAGS.filter((tag) => tag.name.includes(q))
+				: ALL_TAGS;
+			return jsonResponse(filtered);
+		});
+	});
+
+	afterEach(async () => {
+		await act(async () => {
+			root.unmount();
+		});
+		container.remove();
+		vi.restoreAllMocks();
+	});
+
+	function jsonResponse(body: unknown, status = 200) {
+		return new Response(JSON.stringify(body), {
+			status,
+			headers: { "content-type": "application/json" },
+		});
+	}
+
+	type SelectConfig = Parameters<typeof tags.tags.useSelect<Tag>>[0];
+
+	async function renderSelect(
+		config: SelectConfig,
+		onCapture: (result: ResourceSelectResult<Tag>) => void,
+	) {
+		function Probe() {
+			const result = tags.tags.useSelect<Tag>(config);
+			onCapture(result);
+			return null;
+		}
+		await act(async () => {
+			root.render(
+				<StackProvider
+					basePath="/pages"
+					api={{ baseURL: "http://test.local", basePath: "/api/data" }}
+				>
+					<QueryClientProvider client={queryClient}>
+						<Probe />
+					</QueryClientProvider>
+				</StackProvider>,
+			);
+		});
+	}
+
+	async function waitFor(check: () => boolean, timeout = 3000) {
+		const start = Date.now();
+		while (!check()) {
+			if (Date.now() - start > timeout) {
+				throw new Error("waitFor timed out");
+			}
+			await act(async () => {
+				await new Promise((resolve) => setTimeout(resolve, 10));
+			});
+		}
+	}
+
+	const baseConfig: SelectConfig = {
+		searchArgs: (search) => [search],
+		getOptionValue: (tag) => tag.id,
+		getOptionLabel: (tag) => tag.name,
+		debounceMs: 50,
+	};
+
+	it("loads initial options for the empty search", async () => {
+		let select!: ResourceSelectResult<Tag>;
+		await renderSelect(baseConfig, (value) => {
+			select = value;
+		});
+		await waitFor(() => !select.isLoading);
+
+		expect(select.options).toEqual([
+			{ value: "1", label: "alpha", item: ALL_TAGS[0] },
+			{ value: "2", label: "beta", item: ALL_TAGS[1] },
+			{ value: "3", label: "kanban", item: ALL_TAGS[2] },
+		]);
+		expect(select.isSearching).toBe(false);
+	});
+
+	it("debounces the search text and skips intermediate values", async () => {
+		let select!: ResourceSelectResult<Tag>;
+		await renderSelect(baseConfig, (value) => {
+			select = value;
+		});
+		await waitFor(() => !select.isLoading);
+
+		await act(async () => {
+			select.setSearch("k");
+		});
+		await act(async () => {
+			select.setSearch("ka");
+		});
+
+		// Debounce pending: still searching, no new fetch yet
+		expect(select.isSearching).toBe(true);
+		const callsBefore = fetchMock.mock.calls.length;
+
+		await waitFor(
+			() => !select.isSearching && select.options.length === 1,
+			2000,
+		);
+
+		expect(select.options[0]?.label).toBe("kanban");
+
+		// Only the debounced value was fetched — never the intermediate "k"
+		const searchedTerms = fetchMock.mock.calls
+			.slice(callsBefore)
+			.map((call) => new URL(String(call[0])).searchParams.get("q"));
+		expect(searchedTerms).toEqual(["ka"]);
+	});
+
+	it("preloads selected values missing from the options", async () => {
+		let select!: ResourceSelectResult<Tag>;
+		await renderSelect(
+			{
+				...baseConfig,
+				value: "42",
+				preload: { args: (value) => [value] },
+			},
+			(value) => {
+				select = value;
+			},
+		);
+		await waitFor(
+			() => select.options.some((option) => option.value === "42"),
+			2000,
+		);
+
+		expect(select.options).toContainEqual({
+			value: "42",
+			label: "preloaded",
+			item: { id: "42", name: "preloaded" },
+		});
+		expect(select.selectedOptions).toEqual([
+			{
+				value: "42",
+				label: "preloaded",
+				item: { id: "42", name: "preloaded" },
+			},
+		]);
+	});
+
+	it("does not preload values already present in the options", async () => {
+		let select!: ResourceSelectResult<Tag>;
+		await renderSelect(
+			{
+				...baseConfig,
+				value: "2",
+				preload: { args: (value) => [value] },
+			},
+			(value) => {
+				select = value;
+			},
+		);
+		await waitFor(() => !select.isLoading);
+
+		expect(select.selectedOptions).toEqual([
+			{ value: "2", label: "beta", item: ALL_TAGS[1] },
+		]);
+		const detailCalls = fetchMock.mock.calls.filter((call) =>
+			String(call[0]).includes("/tags/one"),
+		);
+		expect(detailCalls).toHaveLength(0);
+	});
+
+	it("falls back to the raw value for unresolvable selections", async () => {
+		let select!: ResourceSelectResult<Tag>;
+		await renderSelect({ ...baseConfig, value: "missing" }, (value) => {
+			select = value;
+		});
+		await waitFor(() => !select.isLoading);
+
+		expect(select.selectedOptions).toEqual([
+			{ value: "missing", label: "missing" },
+		]);
+	});
+});

package/src/__tests__/router-overrides.test.tsx

@@ -0,0 +1,118 @@
+import { describe, expect, it } from "vitest";
+import { renderToString } from "react-dom/server";
+import type { ComponentType } from "react";
+import { StackProvider, usePluginOverrides, useStack } from "../context";
+import type { StackApiConfig, StackRouterConfig } from "../context";
+
+function resolveProvider({
+	pluginName,
+	overrides,
+	router,
+	api,
+	defaultValues,
+}: {
+	pluginName: string;
+	overrides?: Record<string, any>;
+	router?: StackRouterConfig;
+	api?: StackApiConfig;
+	defaultValues?: Record<string, any>;
+}) {
+	let captured: any;
+
+	function Probe() {
+		captured = {
+			stack: useStack(),
+			overrides: usePluginOverrides(pluginName, defaultValues),
+		};
+		return null;
+	}
+
+	renderToString(
+		<StackProvider
+			basePath="/pages"
+			overrides={overrides}
+			router={router}
+			api={api}
+		>
+			<Probe />
+		</StackProvider>,
+	);
+
+	return captured;
+}
+
+const RouterLink: ComponentType<any> = () => null;
+
+describe("top-level router/api context", () => {
+	it("keeps plugin overrides plugin-specific", () => {
+		const blogOverrides = { uploadImage: () => Promise.resolve("image") };
+		const resolved = resolveProvider({
+			pluginName: "blog",
+			overrides: { blog: blogOverrides },
+			router: { Link: RouterLink, navigate: () => {} },
+			api: { baseURL: "https://example.com", basePath: "/api/data" },
+		});
+
+		expect(resolved.overrides).toBe(blogOverrides);
+		expect(resolved.overrides).not.toHaveProperty("Link");
+		expect(resolved.overrides).not.toHaveProperty("apiBaseURL");
+	});
+
+	it("returns an empty override object for an unconfigured plugin", () => {
+		const resolved = resolveProvider({ pluginName: "blog" });
+		expect(resolved.overrides).toEqual({});
+	});
+
+	it("exposes router and API config only at the top level", () => {
+		const navigate = () => {};
+		const refresh = () => {};
+		const api = { baseURL: "https://example.com", basePath: "/api/data" };
+		const resolved = resolveProvider({
+			pluginName: "blog",
+			router: { Link: RouterLink, navigate, refresh },
+			api,
+		});
+
+		expect(resolved.stack.router).toMatchObject({
+			Link: RouterLink,
+			navigate,
+			refresh,
+		});
+		expect(resolved.stack.api).toBe(api);
+		expect(resolved.overrides).toEqual({});
+	});
+
+	it("merges plugin defaults with plugin overrides", () => {
+		const resolved = resolveProvider({
+			pluginName: "blog",
+			overrides: { blog: { showAttribution: false } },
+			defaultValues: {
+				showAttribution: true,
+				localization: { TITLE: "Default" },
+			},
+		});
+
+		expect(resolved.overrides).toEqual({
+			showAttribution: false,
+			localization: { TITLE: "Default" },
+		});
+	});
+
+	it("evaluates the preset useRouter hook over static fields", () => {
+		const staticNavigate = () => {};
+		const hookNavigate = () => {};
+		const hookRefresh = () => {};
+		const resolved = resolveProvider({
+			pluginName: "blog",
+			router: {
+				Link: RouterLink,
+				navigate: staticNavigate,
+				useRouter: () => ({ navigate: hookNavigate, refresh: hookRefresh }),
+			},
+		});
+
+		expect(resolved.stack.router.navigate).toBe(hookNavigate);
+		expect(resolved.stack.router.refresh).toBe(hookRefresh);
+		expect(resolved.stack.router.Link).toBe(RouterLink);
+	});
+});