@btst/stack 3.0.0-rc.1 → 3.0.0-rc.3

package/src/plugins/kanban/__tests__/client-runtime.browser.test.tsx

@@ -0,0 +1,302 @@
+// @vitest-environment jsdom
+import { QueryClient } from "@tanstack/react-query";
+import { act, type ComponentType, type ReactNode } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { renderToString } from "react-dom/server";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createClientStack } from "../../../client";
+import { StackProvider, usePluginSiteNavigation } from "@btst/stack/context";
+import { kanbanClientPlugin, type KanbanPluginOverrides } from "../client";
+import { BoardsListPage } from "../client/components/pages/boards-list-page.internal";
+import { useBoardMutations, useBoards, useResolveUser } from "../client/hooks";
+import { KANBAN_PLUGIN_ID } from "../client/constants";
+
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+const board = {
+	id: "board-1",
+	name: "Roadmap",
+	slug: "roadmap",
+	description: "Team roadmap",
+	ownerId: "owner-1",
+	organizationId: null,
+	columns: [],
+	createdAt: "2026-01-01T00:00:00.000Z",
+	updatedAt: "2026-01-01T00:00:00.000Z",
+};
+
+const requiredKanbanOverrides = {
+	resolveUser: () => null,
+	searchUsers: () => [],
+} satisfies KanbanPluginOverrides;
+
+function jsonResponse(value: unknown) {
+	return new Response(JSON.stringify(value), {
+		status: 200,
+		headers: { "content-type": "application/json" },
+	});
+}
+
+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));
+		});
+	}
+}
+
+describe("Kanban browser runtime", () => {
+	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();
+	});
+
+	it.each([
+		[
+			"same-origin path",
+			{ api: { basePath: "/api/boards" } },
+			/^https:\/\/app\.example\.com\/api\/boards\/boards/,
+		],
+		[
+			"cross-origin endpoint",
+			{
+				api: {
+					baseURL: "https://boards.example.net",
+					basePath: "/btst/kanban",
+					browserHeaders: { "x-public-client": "public-value" },
+					credentials: "include" as const,
+				},
+			},
+			/^https:\/\/boards\.example\.net\/btst\/kanban\/boards/,
+		],
+		[
+			"root-mounted endpoint",
+			{ api: { basePath: "/" } },
+			/^https:\/\/app\.example\.com\/boards(?:\?|$)/,
+		],
+	] as const)(
+		"uses the resolved %s for browser reads and mutations",
+		async (label, endpoint, expectedURL) => {
+			const requests: Array<{
+				url: string;
+				method: string;
+				headers: Headers;
+				credentials?: RequestCredentials;
+			}> = [];
+			vi.spyOn(globalThis, "fetch").mockImplementation(async (input, init) => {
+				const request =
+					input instanceof Request ? input : new Request(input, init);
+				requests.push({
+					url: request.url,
+					method: request.method,
+					headers: request.headers,
+					credentials: request.credentials,
+				});
+				return request.method === "GET"
+					? jsonResponse({ items: [board], total: 1, limit: 50, offset: 0 })
+					: jsonResponse(board);
+			});
+			const browserWindow = globalThis.window;
+			Object.defineProperty(globalThis, "window", {
+				configurable: true,
+				value: undefined,
+			});
+			const stack = (() => {
+				try {
+					return createClientStack({
+						api: {
+							baseURL: "https://app.example.com",
+							basePath: "/api/data",
+							headers: {
+								authorization: "Bearer server-token",
+								cookie: "session=server",
+							},
+						},
+						site: { baseURL: "https://app.example.com", basePath: "/pages" },
+						queryClient: new QueryClient(),
+						plugins: { kanban: kanbanClientPlugin() },
+						endpoints: { kanban: endpoint },
+					});
+				} finally {
+					Object.defineProperty(globalThis, "window", {
+						configurable: true,
+						value: browserWindow,
+					});
+				}
+			})();
+
+			let query: ReturnType<typeof useBoards> | undefined;
+			let mutations: ReturnType<typeof useBoardMutations> | undefined;
+			function Probe() {
+				query = useBoards();
+				mutations = useBoardMutations();
+				return null;
+			}
+
+			await act(async () => {
+				root.render(
+					<StackProvider
+						stack={stack}
+						overrides={{ kanban: requiredKanbanOverrides }}
+					>
+						<Probe />
+					</StackProvider>,
+				);
+			});
+			await waitFor(() => query?.isLoading === false);
+			await act(async () => {
+				await mutations?.createBoard({ name: "Roadmap" });
+			});
+
+			expect(requests.some((request) => request.method === "GET")).toBe(true);
+			expect(requests.some((request) => request.method === "POST")).toBe(true);
+			for (const request of requests) {
+				expect(request.url).toMatch(expectedURL);
+				expect(request.headers.get("authorization")).toBeNull();
+				expect(request.headers.get("cookie")).toBeNull();
+				if (label === "cross-origin endpoint") {
+					expect(request.headers.get("x-public-client")).toBe("public-value");
+					expect(request.credentials).toBe("include");
+				}
+			}
+		},
+	);
+
+	it.each([
+		["root-mounted same-origin", { basePath: "/" }, "/kanban/board-1"],
+		[
+			"cross-origin",
+			{ baseURL: "https://boards.example.net", basePath: "/workspace" },
+			"https://boards.example.net/workspace/kanban/board-1",
+		],
+	] as const)(
+		"renders board links from a %s Kanban site",
+		async (_, site, href) => {
+			vi.spyOn(globalThis, "fetch").mockResolvedValue(
+				jsonResponse({ items: [board], total: 1, limit: 50, offset: 0 }),
+			);
+			const stack = createClientStack({
+				api: { baseURL: "https://app.example.com", basePath: "/api/data" },
+				site: { baseURL: window.location.origin, basePath: "/pages" },
+				queryClient: new QueryClient(),
+				plugins: { kanban: kanbanClientPlugin() },
+				endpoints: {
+					kanban: { site },
+				},
+			});
+
+			await act(async () => {
+				root.render(
+					<StackProvider
+						stack={stack}
+						overrides={{ kanban: requiredKanbanOverrides }}
+					>
+						<BoardsListPage />
+					</StackProvider>,
+				);
+			});
+			await waitFor(() => container.querySelector("a") !== null);
+
+			expect(container.querySelector("a")?.getAttribute("href")).toBe(href);
+		},
+	);
+
+	it("keeps cross-origin Kanban links stable during SSR and hydration", async () => {
+		const stack = createClientStack({
+			api: { baseURL: "https://app.example.com", basePath: "/api/data" },
+			site: { baseURL: "https://app.example.com", basePath: "/pages" },
+			queryClient: new QueryClient(),
+			plugins: { kanban: kanbanClientPlugin() },
+			endpoints: {
+				kanban: {
+					site: {
+						baseURL: "https://boards.example.net",
+						basePath: "/workspace",
+					},
+				},
+			},
+		});
+		function LinkProbe() {
+			const { resolve } = usePluginSiteNavigation(KANBAN_PLUGIN_ID);
+			return <a href={resolve("kanban", "board-1").href}>Board</a>;
+		}
+
+		const browserWindow = globalThis.window;
+		let serverHTML: string;
+		Object.defineProperty(globalThis, "window", {
+			configurable: true,
+			value: undefined,
+		});
+		try {
+			serverHTML = renderToString(
+				<StackProvider
+					stack={stack}
+					overrides={{ kanban: requiredKanbanOverrides }}
+				>
+					<LinkProbe />
+				</StackProvider>,
+			);
+		} finally {
+			Object.defineProperty(globalThis, "window", {
+				configurable: true,
+				value: browserWindow,
+			});
+		}
+
+		expect(serverHTML).toContain(
+			'href="https://boards.example.net/workspace/kanban/board-1"',
+		);
+		await act(async () => {
+			root.render(
+				<StackProvider
+					stack={stack}
+					overrides={{ kanban: requiredKanbanOverrides }}
+				>
+					<LinkProbe />
+				</StackProvider>,
+			);
+		});
+		expect(container.querySelector("a")?.getAttribute("href")).toBe(
+			"https://boards.example.net/workspace/kanban/board-1",
+		);
+	});
+
+	it("explains missing required user workflow callbacks to untyped consumers", () => {
+		const stack = createClientStack({
+			api: { baseURL: "https://app.example.com", basePath: "/api/data" },
+			site: { baseURL: "https://app.example.com", basePath: "/pages" },
+			queryClient: new QueryClient(),
+			plugins: { kanban: kanbanClientPlugin() },
+		});
+		const UnsafeStackProvider = StackProvider as unknown as ComponentType<{
+			stack: typeof stack;
+			children?: ReactNode;
+		}>;
+		function Probe() {
+			useResolveUser("user-1");
+			return null;
+		}
+
+		expect(() =>
+			renderToString(
+				<UnsafeStackProvider stack={stack}>
+					<Probe />
+				</UnsafeStackProvider>,
+			),
+		).toThrowError(
+			/Configure overrides=\{\{ kanban: \{ resolveUser, searchUsers \} \}\}/,
+		);
+	});
+});

package/src/plugins/kanban/__tests__/client-runtime.test.ts

@@ -0,0 +1,130 @@
+import { QueryClient } from "@tanstack/react-query";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createClientStack } from "../../../client";
+import { kanbanClientPlugin, type KanbanClientConfig } from "../client";
+
+function requestDetails(input: RequestInfo | URL, init?: RequestInit) {
+	const request = input instanceof Request ? input : new Request(input, init);
+	return { url: request.url, headers: request.headers };
+}
+
+function jsonResponse(value: unknown, status = 200) {
+	return new Response(JSON.stringify(value), {
+		status,
+		headers: { "content-type": "application/json" },
+	});
+}
+
+afterEach(() => vi.restoreAllMocks());
+
+describe("Kanban resolved client runtime", () => {
+	it("drives loaders, root-mounted metadata, headers, and cache from one runtime", async () => {
+		const queryClient = new QueryClient();
+		const requests: Array<{ url: string; headers: Headers }> = [];
+		vi.spyOn(globalThis, "fetch").mockImplementation(async (input, init) => {
+			requests.push(requestDetails(input, init));
+			return jsonResponse({ items: [], total: 0, limit: 50, offset: 0 });
+		});
+
+		const stack = createClientStack({
+			api: {
+				baseURL: "https://app.example.com",
+				basePath: "/api/data",
+				headers: { cookie: "session=server", "x-request": "request-value" },
+			},
+			site: { baseURL: "https://www.example.com", basePath: "/" },
+			queryClient,
+			plugins: { kanban: kanbanClientPlugin() },
+			endpoints: { kanban: { api: { basePath: "/api/boards" } } },
+		});
+
+		await stack.router.getRoute("/kanban")?.loader?.();
+		await stack.generateSitemap();
+
+		expect(stack.router.getRoute("/kanban")?.meta?.()).toEqual(
+			expect.arrayContaining([
+				{ property: "og:url", content: "https://www.example.com/kanban" },
+			]),
+		);
+		expect(stack.provider.queryClient).toBe(queryClient);
+		expect(queryClient.getQueryCache().getAll()).toHaveLength(1);
+		expect(requests[0]?.url).toMatch(
+			/^https:\/\/app\.example\.com\/api\/boards\/boards\?/,
+		);
+		expect(requests[0]?.headers.get("cookie")).toBe("session=server");
+		expect(requests[0]?.headers.get("x-request")).toBe("request-value");
+		expect(requests[1]?.url).toMatch(
+			/^https:\/\/app\.example\.com\/api\/boards\/boards\?/,
+		);
+		expect(requests[1]?.headers.get("cookie")).toBeNull();
+		expect(requests[1]?.headers.get("x-request")).toBeNull();
+	});
+
+	it("isolates sensitive request headers across a Kanban origin override", async () => {
+		const requests: Headers[] = [];
+		vi.spyOn(globalThis, "fetch").mockImplementation(async (input, init) => {
+			requests.push(requestDetails(input, init).headers);
+			return jsonResponse({ items: [], total: 0, limit: 50, offset: 0 });
+		});
+
+		const stack = createClientStack({
+			api: {
+				baseURL: "https://app.example.com",
+				basePath: "/api/data",
+				headers: {
+					authorization: "Bearer server-token",
+					cookie: "session=server",
+				},
+			},
+			site: { baseURL: "https://app.example.com", basePath: "/pages" },
+			queryClient: new QueryClient(),
+			plugins: { kanban: kanbanClientPlugin() },
+			endpoints: {
+				kanban: {
+					api: {
+						baseURL: "https://boards.example.net",
+						basePath: "/btst/kanban",
+						browserHeaders: { "x-public-client": "public-value" },
+					},
+				},
+			},
+		});
+
+		await stack.router.getRoute("/kanban")?.loader?.();
+
+		expect(requests).toHaveLength(1);
+		expect(requests[0]?.get("authorization")).toBeNull();
+		expect(requests[0]?.get("cookie")).toBeNull();
+		expect(requests[0]?.get("x-public-client")).toBe("public-value");
+	});
+
+	it("does not revive removed transport fields and contains one error report", async () => {
+		vi.spyOn(globalThis, "fetch").mockResolvedValue(
+			jsonResponse({ message: "boards unavailable" }, 500),
+		);
+		const onErrorLoad = vi.fn((_error: Error, _context: unknown) => {
+			throw new Error("reporter unavailable");
+		});
+		const legacyConfig = {
+			headers: { authorization: "Bearer hidden-plugin-token" },
+			hooks: { onErrorLoad },
+		} as unknown as KanbanClientConfig;
+		const stack = createClientStack({
+			api: { baseURL: "https://app.example.com", basePath: "/api/data" },
+			site: { baseURL: "https://app.example.com", basePath: "/pages" },
+			queryClient: new QueryClient(),
+			plugins: { kanban: kanbanClientPlugin(legacyConfig) },
+		});
+
+		await expect(
+			stack.router.getRoute("/kanban")?.loader?.(),
+		).resolves.toBeUndefined();
+		expect(onErrorLoad).toHaveBeenCalledTimes(1);
+		expect(onErrorLoad.mock.calls[0]?.[1]).toMatchObject({
+			path: "/kanban",
+			isSSR: true,
+			apiBaseURL: "https://app.example.com",
+			apiBasePath: "/api/data",
+		});
+	});
+});

package/src/plugins/kanban/__tests__/client-runtime.typecheck.tsx

@@ -0,0 +1,81 @@
+import { QueryClient } from "@tanstack/react-query";
+import { createClientStack } from "../../../client";
+import { StackProvider } from "../../../context";
+import { kanbanClientPlugin, type KanbanClientConfig } from "../client";
+
+const queryClient = new QueryClient();
+const definition = kanbanClientPlugin({
+	hooks: { onErrorLoad: () => undefined },
+});
+
+definition.id satisfies "kanban";
+
+const stack = createClientStack({
+	api: { baseURL: "https://app.example.com", basePath: "/api/data" },
+	site: { baseURL: "https://app.example.com", basePath: "/pages" },
+	queryClient,
+	plugins: { kanban: definition },
+});
+
+// @ts-expect-error Kanban requires its inferred user workflow override block.
+<StackProvider stack={stack} />;
+<StackProvider
+	stack={stack}
+	overrides={{
+		kanban: {
+			resolveUser: () => null,
+			searchUsers: () => [],
+			showAttribution: false,
+		},
+	}}
+/>;
+
+// @ts-expect-error A supplied Kanban override block retains its required user workflow callbacks.
+StackProvider({ stack, overrides: { kanban: { showAttribution: false } } });
+
+// @ts-expect-error Unregistered provider override keys are rejected.
+StackProvider({ stack, overrides: { board: {} } });
+
+createClientStack({
+	api: { baseURL: "https://app.example.com", basePath: "/api/data" },
+	site: { baseURL: "https://app.example.com", basePath: "/pages" },
+	queryClient,
+	plugins: {
+		// @ts-expect-error Registration keys must match the literal Kanban ID.
+		boards: kanbanClientPlugin(),
+	},
+});
+
+const pluginOptions: KanbanClientConfig = {};
+void pluginOptions;
+
+kanbanClientPlugin({
+	// @ts-expect-error Shared API origins belong to createClientStack().
+	apiBaseURL: "https://api.example.com",
+});
+kanbanClientPlugin({
+	// @ts-expect-error Shared API paths belong to createClientStack().
+	apiBasePath: "/api/boards",
+});
+kanbanClientPlugin({
+	// @ts-expect-error Shared site origins belong to createClientStack().
+	siteBaseURL: "https://www.example.com",
+});
+kanbanClientPlugin({
+	// @ts-expect-error Shared site paths belong to createClientStack().
+	siteBasePath: "/boards",
+});
+kanbanClientPlugin({
+	// @ts-expect-error The query client belongs to createClientStack().
+	queryClient,
+});
+kanbanClientPlugin({
+	// @ts-expect-error Request headers belong to createClientStack().api.
+	headers: new Headers(),
+});
+kanbanClientPlugin({
+	hooks: {
+		// @ts-expect-error The canonical loader error callback is onErrorLoad.
+		onLoadError: () => undefined,
+	},
+});