@btst/stack 2.12.2 → 3.0.0-rc.2

package/src/context/router.tsx

@@ -0,0 +1,70 @@
+import type { ComponentType } from "react";
+
+/**
+ * Framework routing primitives shared by all plugins.
+ *
+ * Providing these fields once via the top-level `router` prop on
+ * `StackProvider` makes them available to every plugin.
+ */
+export interface StackRouter {
+	/**
+	 * Link component for navigation
+	 */
+	Link?: ComponentType<React.ComponentProps<"a"> & Record<string, any>>;
+	/**
+	 * Image component for displaying images
+	 */
+	Image?: ComponentType<
+		React.ImgHTMLAttributes<HTMLImageElement> & Record<string, any>
+	>;
+	/**
+	 * Navigation function for programmatic navigation
+	 */
+	navigate?: (path: string) => void | Promise<void>;
+	/**
+	 * Refresh function to invalidate server-side cache (e.g., Next.js router.refresh())
+	 */
+	refresh?: () => void | Promise<void>;
+	/**
+	 * Read the current URL search params
+	 */
+	getSearchParams?: () => URLSearchParams;
+	/**
+	 * Replace the current URL search params
+	 */
+	setSearchParams?: (
+		next: URLSearchParams,
+		opts?: { replace?: boolean },
+	) => void;
+}
+
+/**
+ * Config accepted by the `router` prop on `StackProvider`.
+ *
+ * Framework presets (`nextRouter()`, `reactRouter()`, `tanstackRouter()`) are
+ * plain objects created anywhere — including module scope — so fields that
+ * need framework hooks are produced by the optional `useRouter` hook, which
+ * `StackProvider` evaluates internally. Hook results are merged over the
+ * static fields.
+ */
+export interface StackRouterConfig extends StackRouter {
+	/**
+	 * Optional hook evaluated inside `StackProvider`. Use this for router
+	 * fields that must be derived from framework hooks (e.g. `useNavigate`).
+	 */
+	useRouter?: () => StackRouter;
+}
+
+/**
+ * Top-level API config used by all plugin components.
+ */
+export interface StackApiConfig {
+	/**
+	 * API base URL (e.g. `https://example.com`)
+	 */
+	baseURL: string;
+	/**
+	 * API base path (e.g. `/api/data`)
+	 */
+	basePath: string;
+}

package/src/next/handlers.ts

@@ -0,0 +1,24 @@
+import type { StackRequestHandler } from "../shared/entry-factories";
+
+/**
+ * Wires a BTST API handler to the five HTTP method exports a Next.js route
+ * handler file needs.
+ *
+ * @example
+ * ```ts
+ * // app/api/data/[[...all]]/route.ts
+ * import { toNextRouteHandlers } from "@btst/stack/next";
+ * import { handler } from "@/lib/stack";
+ *
+ * export const { GET, POST, PUT, PATCH, DELETE } = toNextRouteHandlers(handler);
+ * ```
+ */
+export function toNextRouteHandlers(handler: StackRequestHandler) {
+	return {
+		GET: handler,
+		POST: handler,
+		PUT: handler,
+		PATCH: handler,
+		DELETE: handler,
+	};
+}

package/src/next/index.tsx

@@ -0,0 +1,13 @@
+export { toNextRouteHandlers } from "./handlers";
+export {
+	type CreateNextPageOptions,
+	type GetNextStackClient,
+	type NextPageProps,
+	createNextPage,
+} from "./page";
+export { nextRouter } from "./router";
+export type {
+	GetStackClient,
+	ResolveStackClient,
+	StackRequestHandler,
+} from "../shared/entry-factories";

package/src/next/page.tsx

@@ -0,0 +1,114 @@
+import { HydrationBoundary, dehydrate } from "@tanstack/react-query";
+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 { metaElementsToObject } from "../client/meta-utils";
+import { normalizePath } from "../client/path-utils";
+import {
+	type ResolveStackClient,
+	stackDehydrateOptions,
+} from "../shared/entry-factories";
+
+export interface NextPageProps {
+	params: Promise<{ all?: string[] }>;
+}
+
+/** Resolves the stack client for a Next.js page or metadata request. */
+export type GetNextStackClient = ResolveStackClient<NextPageProps>;
+
+export interface CreateNextPageOptions {
+	/**
+	 * Returns the stack client for the current request. May be async and receives
+	 * the page props so request-aware clients can resolve request-local state.
+	 */
+	getStackClient: GetNextStackClient;
+	/** Returns the QueryClient for the current context (`lib/query-client`). */
+	getQueryClient: () => QueryClient;
+	/**
+	 * Called when no route matches the path. Defaults to `notFound()` from
+	 * `next/navigation`.
+	 */
+	notFound?: () => never;
+	/** Wraps the rendered page (inside the `HydrationBoundary`). */
+	wrapPage?: (page: ReactNode) => ReactNode;
+	/**
+	 * Options passed to `dehydrate()`. Defaults to dehydrating failed queries
+	 * in addition to the React Query defaults, so the client does not refetch
+	 * queries that errored during SSR. Override e.g. to sanitize error
+	 * payloads before they are serialized into the HTML.
+	 */
+	dehydrateOptions?: DehydrateOptions;
+}
+
+/**
+ * Creates the Next.js catch-all page for BTST plugin routes: SSR prefetch via
+ * `route.loader()`, React Query dehydration (including failed queries),
+ * `generateMetadata` with loader-before-meta ordering, and 404 via
+ * `notFound()`.
+ *
+ * @example
+ * ```tsx
+ * // app/pages/[[...all]]/page.tsx
+ * import { createNextPage } from "@btst/stack/next";
+ * import { getOrCreateQueryClient } from "@/lib/query-client";
+ * import { getStackClient } from "@/lib/stack-client";
+ *
+ * export const dynamic = "force-dynamic";
+ * const page = createNextPage({ getStackClient, getQueryClient: getOrCreateQueryClient });
+ * export default page.Page;
+ * export const generateMetadata = page.generateMetadata;
+ * ```
+ */
+export function createNextPage(options: CreateNextPageOptions) {
+	const {
+		getStackClient,
+		getQueryClient,
+		notFound = nextNotFound,
+		wrapPage,
+		dehydrateOptions = stackDehydrateOptions,
+	} = options;
+
+	async function Page(pageProps: NextPageProps) {
+		const { params } = pageProps;
+		const pathParams = await params;
+		const path = normalizePath(pathParams?.all);
+		const queryClient = getQueryClient();
+		const stackClient = await getStackClient(queryClient, pageProps);
+		const route = stackClient.router.getRoute(path);
+
+		if (route?.loader) {
+			await route.loader();
+		}
+
+		const page = route?.PageComponent ? <route.PageComponent /> : notFound();
+
+		return (
+			<HydrationBoundary state={dehydrate(queryClient, dehydrateOptions)}>
+				{wrapPage ? wrapPage(page) : page}
+			</HydrationBoundary>
+		);
+	}
+
+	async function generateMetadata(pageProps: NextPageProps): Promise<Metadata> {
+		const { params } = pageProps;
+		const pathParams = await params;
+		const path = normalizePath(pathParams?.all);
+		const queryClient = getQueryClient();
+		const stackClient = await getStackClient(queryClient, pageProps);
+		const route = stackClient.router.getRoute(path);
+
+		if (!route) {
+			return notFound();
+		}
+		if (!route.meta) {
+			return {};
+		}
+		if (route.loader) {
+			await route.loader();
+		}
+		return metaElementsToObject(await route.meta()) satisfies Metadata;
+	}
+
+	return { Page, generateMetadata };
+}

package/src/next/router.tsx

@@ -0,0 +1,102 @@
+"use client";
+import NextImage from "next/image";
+import NextLink from "next/link";
+import { useRouter } from "next/navigation";
+import { useMemo } from "react";
+import type { StackRouter, StackRouterConfig } from "../context/router";
+
+function NextLinkWrapper({
+	href,
+	...props
+}: React.ComponentProps<"a"> & Record<string, any>) {
+	return <NextLink href={href || "#"} {...props} />;
+}
+
+/**
+ * Next.js Image wrapper for plugins.
+ * Handles both cases: with explicit dimensions or using fill mode.
+ */
+function NextImageWrapper(props: React.ImgHTMLAttributes<HTMLImageElement>) {
+	const { alt = "", src = "", width, height, ...rest } = props;
+
+	// Use fill mode if width or height are not provided
+	if (!width || !height) {
+		return (
+			<span className="block relative w-full h-full">
+				<NextImage
+					alt={alt}
+					src={typeof src === "string" ? src : ""}
+					fill
+					sizes="400px"
+					{...rest}
+				/>
+			</span>
+		);
+	}
+
+	return (
+		<NextImage
+			alt={alt}
+			src={typeof src === "string" ? src : ""}
+			width={width as number}
+			height={height as number}
+			{...rest}
+		/>
+	);
+}
+
+// Reads window.location.search instead of Next's useSearchParams() hook to
+// avoid forcing a Suspense/CSR bailout during static generation. Returns
+// empty params on the server.
+function getSearchParams(): URLSearchParams {
+	return new URLSearchParams(
+		typeof window !== "undefined" ? window.location.search : "",
+	);
+}
+
+function useNextStackRouter(): StackRouter {
+	const router = useRouter();
+
+	return useMemo(
+		() => ({
+			navigate: (path: string) => {
+				router.push(path);
+			},
+			refresh: () => {
+				router.refresh();
+			},
+			setSearchParams: (
+				next: URLSearchParams,
+				opts?: { replace?: boolean },
+			) => {
+				const query = next.toString();
+				const path = `${window.location.pathname}${query ? `?${query}` : ""}`;
+				if (opts?.replace) {
+					router.replace(path);
+				} else {
+					router.push(path);
+				}
+			},
+		}),
+		[router],
+	);
+}
+
+/**
+ * Router preset for Next.js (App Router).
+ *
+ * @example
+ * ```tsx
+ * import { nextRouter } from "@btst/stack/next";
+ *
+ * <StackProvider basePath="/pages" router={nextRouter()} api={{ baseURL, basePath: "/api/data" }}>
+ * ```
+ */
+export function nextRouter(): StackRouterConfig {
+	return {
+		Link: NextLinkWrapper,
+		Image: NextImageWrapper,
+		getSearchParams,
+		useRouter: useNextStackRouter,
+	};
+}

package/src/plugins/ai-chat/__tests__/client-sweep.test.tsx

@@ -0,0 +1,317 @@
+// @vitest-environment jsdom
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+	StackProvider,
+	type StackAuthProvider,
+	type StackI18nProvider,
+} from "@btst/stack/context";
+import { ChatInterface } from "../client/components/chat-interface";
+import { ChatSidebar } from "../client/components/chat-sidebar";
+import { ChatPage } from "../client/components/pages/chat-page.internal";
+import type { SerializedConversation } from "../types";
+
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+(globalThis as any).ResizeObserver ??= class {
+	observe() {}
+	unobserve() {}
+	disconnect() {}
+};
+Element.prototype.scrollIntoView ??= () => {};
+
+const mocks = vi.hoisted(() => ({
+	useChat: vi.fn(),
+	useConversation: vi.fn(),
+	useConversations: vi.fn(),
+	useRenameConversationForm: vi.fn(),
+	useDeleteConversation: vi.fn(),
+	chatLayout: vi.fn(),
+}));
+
+vi.mock("@ai-sdk/react", () => ({ useChat: mocks.useChat }));
+vi.mock("../client/hooks/chat-hooks", () => ({
+	useConversation: mocks.useConversation,
+	useConversations: mocks.useConversations,
+	useRenameConversationForm: mocks.useRenameConversationForm,
+	useDeleteConversation: mocks.useDeleteConversation,
+}));
+vi.mock("../client/components/chat-input", () => ({
+	ChatInput: ({ placeholder }: { placeholder?: string }) => (
+		<div data-testid="chat-input">{placeholder}</div>
+	),
+}));
+vi.mock("../client/components/chat-message", () => ({
+	ChatMessage: () => <div data-testid="chat-message" />,
+}));
+vi.mock("../client/components/chat-layout", () => ({
+	ChatLayout: (props: unknown) => {
+		mocks.chatLayout(props);
+		return <div data-testid="chat-layout" />;
+	},
+}));
+
+const conversation: SerializedConversation = {
+	id: "conv-1",
+	title: "First conversation",
+	createdAt: new Date("2024-01-01").toISOString(),
+	updatedAt: new Date("2024-01-02").toISOString(),
+};
+
+let container: HTMLDivElement;
+let root: Root;
+let queryClient: QueryClient;
+let deleteConversation: ReturnType<typeof vi.fn>;
+
+beforeEach(() => {
+	container = document.createElement("div");
+	document.body.appendChild(container);
+	root = createRoot(container);
+	queryClient = new QueryClient({
+		defaultOptions: { queries: { retry: false } },
+	});
+	deleteConversation = vi.fn().mockResolvedValue({ success: true });
+
+	mocks.useChat.mockReturnValue({
+		messages: [],
+		sendMessage: vi.fn(),
+		status: "ready",
+		error: null,
+		setMessages: vi.fn(),
+		regenerate: vi.fn(),
+		addToolOutput: vi.fn(),
+	});
+	mocks.useConversation.mockReturnValue({
+		conversation: null,
+		isLoading: false,
+		error: null,
+		refetch: vi.fn(),
+	});
+	mocks.useConversations.mockReturnValue({
+		conversations: [conversation],
+		isLoading: false,
+		error: null,
+		refetch: vi.fn(),
+	});
+	mocks.useRenameConversationForm.mockReturnValue({
+		submit: vi.fn().mockResolvedValue(conversation),
+		isSubmitting: false,
+		error: null,
+		fieldErrors: {},
+		clearErrors: vi.fn(),
+	});
+	mocks.useDeleteConversation.mockReturnValue({
+		mutateAsync: deleteConversation,
+		isPending: false,
+	});
+});
+
+afterEach(async () => {
+	await act(async () => root.unmount());
+	container.remove();
+	document.body.innerHTML = "";
+	queryClient.clear();
+	vi.clearAllMocks();
+});
+
+const router = () => ({
+	navigate: vi.fn(),
+	getSearchParams: () => new URLSearchParams(),
+	setSearchParams: vi.fn(),
+});
+
+function overrides(
+	mode: "authenticated" | "public" = "authenticated",
+	localization?: Record<string, string>,
+) {
+	return {
+		mode,
+		localization,
+	};
+}
+
+async function render(
+	ui: React.ReactElement,
+	options: {
+		auth?: StackAuthProvider;
+		i18n?: StackI18nProvider;
+		notify?: {
+			success: ReturnType<typeof vi.fn>;
+			error: ReturnType<typeof vi.fn>;
+		};
+		mode?: "authenticated" | "public";
+		localization?: Record<string, string>;
+	} = {},
+) {
+	await act(async () => {
+		root.render(
+			<QueryClientProvider client={queryClient}>
+				<StackProvider
+					basePath="/pages"
+					api={{ baseURL: "http://test.local", basePath: "/api/data" }}
+					router={router()}
+					overrides={{
+						"ai-chat": overrides(options.mode, options.localization),
+					}}
+					auth={options.auth}
+					i18n={options.i18n}
+					notify={options.notify}
+				>
+					{ui}
+				</StackProvider>
+			</QueryClientProvider>,
+		);
+		await Promise.resolve();
+	});
+}
+
+async function openConversationMenu() {
+	const trigger = container.querySelector<HTMLButtonElement>(
+		'button[aria-label="Conversation actions"]',
+	)!;
+	await act(async () => {
+		trigger.dispatchEvent(
+			new MouseEvent("pointerdown", { bubbles: true, button: 0 }),
+		);
+	});
+}
+
+function menuItem(text: string) {
+	return Array.from(
+		document.querySelectorAll<HTMLElement>("[role=menuitem]"),
+	).find((item) => item.textContent?.includes(text));
+}
+
+describe("AI Chat permissions", () => {
+	it("keeps public chat writable when an auth provider denies every action", async () => {
+		const can = vi.fn(() => false);
+		await render(<ChatInterface />, {
+			mode: "public",
+			auth: { getIdentity: () => null, can },
+		});
+
+		expect(container.querySelector('[data-testid="chat-input"]')).toBeTruthy();
+	});
+
+	it("gates authenticated create and per-conversation controls independently", async () => {
+		const can = vi.fn(
+			({ action }: { action: string }) =>
+				action === "read" || action === "delete",
+		);
+		const auth: StackAuthProvider = {
+			getIdentity: () => ({ id: "viewer" }),
+			can,
+		};
+
+		await render(<ChatSidebar />, { auth });
+		expect(document.body.textContent).not.toContain("New chat");
+
+		await openConversationMenu();
+		expect(menuItem("Rename")).toBeUndefined();
+		expect(menuItem("Delete")).toBeTruthy();
+		expect(can).toHaveBeenCalledWith(
+			expect.objectContaining({
+				resource: "ai-chat:conversation",
+				action: "delete",
+				params: { id: conversation.id },
+			}),
+		);
+	});
+});
+
+describe("AI Chat forms, notifications, and i18n", () => {
+	it("renders rename field errors inline through the i18n catalog", async () => {
+		mocks.useRenameConversationForm.mockReturnValue({
+			submit: vi.fn(),
+			isSubmitting: false,
+			error: new Error("Validation failed"),
+			fieldErrors: { title: "Title is required" },
+			clearErrors: vi.fn(),
+		});
+		await render(<ChatSidebar />, {
+			i18n: {
+				translate: (key, fallback) =>
+					key === "aiChat.conversation.titleRequired"
+						? "Titel erforderlich"
+						: fallback,
+			},
+		});
+
+		await openConversationMenu();
+		await act(async () => menuItem("Rename")?.click());
+		expect(document.body.textContent).toContain("Titel erforderlich");
+	});
+
+	it("lets legacy localization overrides win over the i18n catalog", async () => {
+		await render(<ChatSidebar />, {
+			i18n: { translate: () => "Catalog new chat" },
+			localization: { SIDEBAR_NEW_CHAT: "Legacy new chat" },
+		});
+
+		expect(document.body.textContent).toContain("Legacy new chat");
+		expect(document.body.textContent).not.toContain("Catalog new chat");
+	});
+
+	it("routes delete success through the notify provider", async () => {
+		const notify = { success: vi.fn(), error: vi.fn() };
+		await render(<ChatSidebar />, { notify });
+
+		await openConversationMenu();
+		await act(async () => menuItem("Delete")?.click());
+		const confirm = Array.from(
+			document.querySelectorAll<HTMLButtonElement>("button"),
+		).find((button) => button.textContent === "Delete");
+		await act(async () => confirm?.click());
+
+		expect(deleteConversation).toHaveBeenCalledWith({ id: conversation.id });
+		expect(notify.success).toHaveBeenCalledWith("Conversation deleted");
+		expect(notify.error).not.toHaveBeenCalled();
+	});
+
+	it("does not expose raw delete errors through notifications", async () => {
+		const notify = { success: vi.fn(), error: vi.fn() };
+		deleteConversation.mockRejectedValueOnce(
+			new Error("internal database detail"),
+		);
+		await render(<ChatSidebar />, { notify });
+
+		await openConversationMenu();
+		await act(async () => menuItem("Delete")?.click());
+		const confirm = Array.from(
+			document.querySelectorAll<HTMLButtonElement>("button"),
+		).find((button) => button.textContent === "Delete");
+		await act(async () => confirm?.click());
+
+		expect(notify.error).toHaveBeenCalledWith("Failed to delete conversation");
+		expect(notify.error).not.toHaveBeenCalledWith("internal database detail");
+	});
+});
+
+describe("AI Chat route lifecycle", () => {
+	it("runs the conversation render hook", async () => {
+		const onRouteRender = vi.fn();
+		await act(async () => {
+			root.render(
+				<StackProvider
+					basePath="/pages"
+					router={router()}
+					overrides={{
+						"ai-chat": {
+							...overrides(),
+							onRouteRender,
+						},
+					}}
+				>
+					<ChatPage conversationId="conv-1" />
+				</StackProvider>,
+			);
+			await Promise.resolve();
+		});
+
+		expect(onRouteRender).toHaveBeenCalledWith(
+			"chatConversation",
+			expect.objectContaining({ path: "/chat/conv-1" }),
+		);
+	});
+});