@btst/stack 4.0.0 → 4.1.1

package/dist/shared/{stack.5_zzCejP.d.ts → stack.rVF0f509.d.ts}

@@ -204,6 +204,26 @@ interface AiChatPluginOverrides {
      * ```
      */
     toolRenderers?: Record<string, ToolCallRenderer>;
+    /**
+     * Optional class names merged onto specific UI elements.
+     * Use these for targeted styling without replacing whole components.
+     */
+    classNames?: {
+        /** Root of `ChatLayout` (full-page or widget mode) */
+        container?: string;
+        /** Conversation sidebar root */
+        sidebar?: string;
+        /** Wrapper around the list of messages */
+        messageList?: string;
+        /** Each message row (user and assistant) */
+        message?: string;
+        /** The bubble of a user message */
+        userMessage?: string;
+        /** The bubble of an assistant message */
+        assistantMessage?: string;
+        /** The composer form at the bottom of the chat */
+        input?: string;
+    };
     /**
      * Called when a route is rendered
      * @param routeName - Name of the route (e.g., 'chat', 'chatConversation')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btst/stack",
-  "version": "4.0.0",
+  "version": "4.1.1",
   "description": "A composable, plugin-based library for building full-stack applications.",
   "repository": {
     "type": "git",

package/src/plugins/ai-chat/__tests__/classnames-overrides.test.tsx

@@ -0,0 +1,248 @@
+// @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";
+// Core primitives MUST be imported from the package entry (not relative src
+// paths) so they share module identity — and React context — with the plugin
+// components, which resolve `@btst/stack/*` via package self-reference.
+import { StackProvider } from "@btst/stack/context";
+import type { UIMessage } from "ai";
+import { ChatInput } from "../client/components/chat-input";
+import { ChatLayout } from "../client/components/chat-layout";
+import { ChatMessage } from "../client/components/chat-message";
+import { aiChatClientPlugin } from "../client/plugin";
+import type { SerializedConversation } from "../types";
+import { createTestClientStack } from "../../../__tests__/client-stack-test-utils";
+
+(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(),
+	useAiChatIdentityPartition: vi.fn(),
+}));
+
+vi.mock("@ai-sdk/react", () => ({ useChat: mocks.useChat }));
+vi.mock("../client/hooks/chat-hooks", () => ({
+	useAiChatIdentityPartition: mocks.useAiChatIdentityPartition,
+	useConversation: mocks.useConversation,
+	useConversations: mocks.useConversations,
+	useRenameConversationForm: mocks.useRenameConversationForm,
+	useDeleteConversation: mocks.useDeleteConversation,
+}));
+vi.mock("../client/context/page-ai-context", () => ({
+	usePageAIContext: () => undefined,
+}));
+// Markdown rendering is unrelated to class wiring and drags in highlight/katex.
+vi.mock("@workspace/ui/components/markdown-content", () => ({
+	MarkdownContent: ({ content }: { content: string }) => <div>{content}</div>,
+}));
+
+const CLASS_NAMES = {
+	container: "bg-red-100",
+	sidebar: "bg-blue-100",
+	messageList: "bg-yellow-50",
+	message: "text-purple-700",
+	userMessage: "border-4 border-orange-500",
+	assistantMessage: "border-4 border-green-500",
+	input: "bg-pink-100",
+} as const;
+
+const conversation: SerializedConversation = {
+	id: "conv-1",
+	userId: "owner-1",
+	title: "First conversation",
+	createdAt: new Date("2024-01-01").toISOString(),
+	updatedAt: new Date("2024-01-02").toISOString(),
+};
+
+const userMessage: UIMessage = {
+	id: "user-1",
+	role: "user",
+	parts: [{ type: "text", text: "Hi there" }],
+};
+const assistantMessage: UIMessage = {
+	id: "assistant-1",
+	role: "assistant",
+	parts: [{ type: "text", text: "Hello back" }],
+};
+
+let container: HTMLDivElement;
+let root: Root;
+let queryClient: QueryClient;
+
+beforeEach(() => {
+	container = document.createElement("div");
+	document.body.appendChild(container);
+	root = createRoot(container);
+	queryClient = new QueryClient({
+		defaultOptions: { queries: { retry: false } },
+	});
+
+	mocks.useAiChatIdentityPartition.mockReturnValue("anonymous");
+	mocks.useChat.mockReturnValue({
+		messages: [userMessage, assistantMessage],
+		sendMessage: vi.fn(),
+		status: "ready",
+		error: null,
+		setMessages: vi.fn(),
+		regenerate: vi.fn(),
+		addToolOutput: vi.fn(),
+		stop: 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(),
+		isSubmitting: false,
+		error: null,
+		fieldErrors: {},
+		clearErrors: vi.fn(),
+	});
+	mocks.useDeleteConversation.mockReturnValue({
+		mutateAsync: vi.fn(),
+		isPending: false,
+	});
+});
+
+afterEach(async () => {
+	await act(async () => {
+		root.unmount();
+	});
+	container.remove();
+	vi.clearAllMocks();
+});
+
+async function render(ui: React.ReactElement) {
+	await act(async () => {
+		root.render(
+			<QueryClientProvider client={queryClient}>
+				<StackProvider
+					stack={createTestClientStack(
+						{ aiChat: aiChatClientPlugin() },
+						queryClient,
+					)}
+					overrides={{ aiChat: { classNames: CLASS_NAMES } }}
+				>
+					{ui}
+				</StackProvider>
+			</QueryClientProvider>,
+		);
+	});
+}
+
+function query(selector: string): HTMLElement {
+	const el = container.querySelector<HTMLElement>(selector);
+	expect(el, `expected to find ${selector}`).toBeTruthy();
+	return el!;
+}
+
+describe("ai-chat classNames overrides (issue #36)", () => {
+	it("applies message, userMessage and assistantMessage to a user message", async () => {
+		await render(<ChatMessage message={userMessage} />);
+
+		const row = query('[data-testid="chat-message"][data-role="user"]');
+		expect(row.className).toContain(CLASS_NAMES.message);
+		expect(row.className).toContain("justify-end");
+
+		const bubble = query('[data-testid="chat-message-bubble"]');
+		expect(bubble.className).toContain("border-orange-500");
+		expect(bubble.className).not.toContain("border-green-500");
+		// The role-specific base styling is preserved.
+		expect(bubble.className).toContain("bg-primary");
+	});
+
+	it("applies assistantMessage (not userMessage) to an assistant message", async () => {
+		await render(<ChatMessage message={assistantMessage} />);
+
+		const row = query('[data-testid="chat-message"][data-role="assistant"]');
+		expect(row.className).toContain(CLASS_NAMES.message);
+		expect(row.className).toContain("justify-start");
+
+		const bubble = query('[data-testid="chat-message-bubble"]');
+		expect(bubble.className).toContain("border-green-500");
+		expect(bubble.className).not.toContain("border-orange-500");
+		expect(bubble.className).toContain("bg-muted");
+	});
+
+	it("applies classNames.input to the composer form", async () => {
+		await render(
+			<ChatInput
+				handleInputChange={() => {}}
+				handleSubmit={() => {}}
+				isLoading={false}
+			/>,
+		);
+
+		const form = query('[data-testid="chat-input-form"]');
+		expect(form.tagName).toBe("FORM");
+		expect(form.className).toContain(CLASS_NAMES.input);
+		expect(form.className).toContain("space-y-2");
+	});
+
+	it("applies container, sidebar and messageList in the full layout", async () => {
+		await render(<ChatLayout conversationId={conversation.id} />);
+
+		const layout = query('[data-testid="chat-layout"]');
+		expect(layout.className).toContain(CLASS_NAMES.container);
+		expect(layout.className).toContain("overflow-hidden");
+
+		const sidebar = query('[data-testid="chat-sidebar"]');
+		expect(sidebar.className).toContain(CLASS_NAMES.sidebar);
+		expect(sidebar.className).toContain("border-r");
+
+		const list = query('[data-testid="chat-message-list"]');
+		expect(list.className).toContain(CLASS_NAMES.messageList);
+		expect(list.className).toContain("flex-col");
+	});
+
+	it("applies classNames.container to the widget root", async () => {
+		await render(<ChatLayout layout="widget" />);
+
+		const trigger = query('[data-testid="widget-trigger"]');
+		const widgetRoot = trigger.parentElement!;
+		expect(widgetRoot.className).toContain(CLASS_NAMES.container);
+		expect(widgetRoot.className).toContain("items-end");
+	});
+
+	it("leaves base classes untouched when no classNames override is supplied", async () => {
+		await act(async () => {
+			root.render(
+				<QueryClientProvider client={queryClient}>
+					<StackProvider
+						stack={createTestClientStack(
+							{ aiChat: aiChatClientPlugin() },
+							queryClient,
+						)}
+					>
+						<ChatMessage message={userMessage} />
+					</StackProvider>
+				</QueryClientProvider>,
+			);
+		});
+
+		const bubble = query('[data-testid="chat-message-bubble"]');
+		expect(bubble.className).toContain("bg-primary");
+		expect(bubble.className).not.toContain("border-orange-500");
+	});
+});

package/src/plugins/ai-chat/client/components/chat-input.tsx

@@ -93,6 +93,7 @@ export function ChatInput({
 		uploadFile,
 		localization: customLocalization,
 		allowedFileTypes,
+		classNames,
 	} = usePluginOverrides<AiChatPluginOverrides, Partial<AiChatPluginOverrides>>(
 		"aiChat",
 		{},
@@ -314,7 +315,11 @@ export function ChatInput({
 					)}
 				</PermissionCheck>
 			)}
-			<form onSubmit={handleFormSubmit} className="space-y-2">
+			<form
+				onSubmit={handleFormSubmit}
+				className={cn("space-y-2", classNames?.input)}
+				data-testid="chat-input-form"
+			>
 				{/* Attached Files Preview */}
 				{attachedFiles.length > 0 && (
 					<div className="flex flex-wrap gap-2">

package/src/plugins/ai-chat/client/components/chat-interface.tsx

@@ -263,6 +263,7 @@ export function ChatInterface({
 		localization: customLocalization,
 		showAttribution,
 		chatSuggestions,
+		classNames,
 	} = usePluginOverrides<AiChatPluginOverrides, Partial<AiChatPluginOverrides>>(
 		"aiChat",
 		{ showAttribution: true },
@@ -1139,7 +1140,9 @@ export function ChatInterface({
 							className={cn(
 								"flex flex-col p-4",
 								isWidget ? "max-w-full" : "max-w-3xl mx-auto w-full",
+								classNames?.messageList,
 							)}
+							data-testid="chat-message-list"
 						>
 							{messages.length === 0 ? (
 								<div className="flex flex-col h-full min-h-[300px]">

package/src/plugins/ai-chat/client/components/chat-layout.tsx

@@ -86,7 +86,7 @@ export function ChatLayout(props: ChatLayoutProps) {
 		onMessagesChange,
 		onClear,
 	} = props;
-	const { localization } = usePluginOverrides<
+	const { localization, classNames } = usePluginOverrides<
 		AiChatPluginOverrides,
 		Partial<AiChatPluginOverrides>
 	>("aiChat", {});
@@ -133,7 +133,13 @@ export function ChatLayout(props: ChatLayoutProps) {
 
 	if (layout === "widget") {
 		return (
-			<div className={cn("flex flex-col items-end gap-3", className)}>
+			<div
+				className={cn(
+					"flex flex-col items-end gap-3",
+					className,
+					classNames?.container,
+				)}
+			>
 				{/* Chat panel — always mounted to preserve conversation state, hidden when closed */}
 				<div
 					className={cn(
@@ -238,6 +244,7 @@ export function ChatLayout(props: ChatLayoutProps) {
 			className={cn(
 				"flex h-[calc(100vh-4rem)] w-full overflow-hidden",
 				className,
+				classNames?.container,
 			)}
 			data-testid="chat-layout"
 		>

package/src/plugins/ai-chat/client/components/chat-message.tsx

@@ -133,11 +133,14 @@ export function ChatMessage({
 }: ChatMessageProps) {
 	const isUser = message.role === "user";
 
-	const { localization: customLocalization, toolRenderers } =
-		usePluginOverrides<AiChatPluginOverrides, Partial<AiChatPluginOverrides>>(
-			"aiChat",
-			{},
-		);
+	const {
+		localization: customLocalization,
+		toolRenderers,
+		classNames,
+	} = usePluginOverrides<AiChatPluginOverrides, Partial<AiChatPluginOverrides>>(
+		"aiChat",
+		{},
+	);
 	const { router } = useStack();
 	const Link = router?.Link;
 	const Image = router?.Image;
@@ -265,7 +268,10 @@ export function ChatMessage({
 				"flex gap-3 w-full",
 				isCompact ? "mb-3" : "mb-4",
 				isUser ? "justify-end" : "justify-start",
+				classNames?.message,
 			)}
+			data-testid="chat-message"
+			data-role={message.role}
 			aria-label={
 				isUser
 					? tr("A11Y_USER_MESSAGE", "aiChat.a11y.userMessage", "Your message")
@@ -295,7 +301,9 @@ export function ChatMessage({
 						"rounded-lg",
 						isCompact ? "px-3 py-2" : "px-4 py-3",
 						isUser ? "bg-primary text-primary-foreground" : "bg-muted",
+						isUser ? classNames?.userMessage : classNames?.assistantMessage,
 					)}
+					data-testid="chat-message-bubble"
 				>
 					{isUser ? (
 						// User messages: files + images + text (or edit mode)

package/src/plugins/ai-chat/client/components/chat-sidebar.tsx

@@ -67,7 +67,7 @@ export function ChatSidebar({
 	onNewChat,
 	className,
 }: ChatSidebarProps) {
-	const { localization: customLocalization } = usePluginOverrides<
+	const { localization: customLocalization, classNames } = usePluginOverrides<
 		AiChatPluginOverrides,
 		Partial<AiChatPluginOverrides>
 	>("aiChat", {});
@@ -208,7 +208,11 @@ export function ChatSidebar({
 	return (
 		<div
 			data-testid="chat-sidebar"
-			className={cn("flex flex-col h-full bg-muted/30 border-r", className)}
+			className={cn(
+				"flex flex-col h-full bg-muted/30 border-r",
+				className,
+				classNames?.sidebar,
+			)}
 		>
 			{/* Header */}
 			<div className="p-4 border-b">

package/src/plugins/ai-chat/client/overrides.ts

@@ -201,6 +201,27 @@ export interface AiChatPluginOverrides {
 	 */
 	toolRenderers?: Record<string, ToolCallRenderer>;
 
+	/**
+	 * Optional class names merged onto specific UI elements.
+	 * Use these for targeted styling without replacing whole components.
+	 */
+	classNames?: {
+		/** Root of `ChatLayout` (full-page or widget mode) */
+		container?: string;
+		/** Conversation sidebar root */
+		sidebar?: string;
+		/** Wrapper around the list of messages */
+		messageList?: string;
+		/** Each message row (user and assistant) */
+		message?: string;
+		/** The bubble of a user message */
+		userMessage?: string;
+		/** The bubble of an assistant message */
+		assistantMessage?: string;
+		/** The composer form at the bottom of the chat */
+		input?: string;
+	};
+
 	// ============== Lifecycle Hooks (optional) ==============
 
 	/**

package/src/plugins/blog/__tests__/classnames-overrides.test.tsx

@@ -0,0 +1,206 @@
+// @vitest-environment jsdom
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+// Core primitives MUST be imported from the package entry (not relative src
+// paths) so they share module identity — and React context — with the blog
+// components, which resolve `@btst/stack/*` via package self-reference.
+import { StackProvider } from "@btst/stack/context";
+import { PageWrapper } from "../client/components/shared/page-wrapper";
+import { PostsList } from "../client/components/shared/posts-list";
+import type { SerializedPost } from "../types";
+import { createTestClientStack } from "../../../__tests__/client-stack-test-utils";
+import { blogClientPlugin } from "../client/plugin";
+
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+// jsdom lacks these APIs used by Radix / cmdk inside SearchInput
+(globalThis as any).ResizeObserver ??= class {
+	observe() {}
+	unobserve() {}
+	disconnect() {}
+};
+Element.prototype.scrollIntoView ??= () => {};
+
+const hooks = vi.hoisted(() => ({
+	useSuspensePost: vi.fn(),
+	useDeletePost: vi.fn(),
+	usePostForm: vi.fn(),
+	usePostSearch: vi.fn(),
+	useSuspensePosts: vi.fn(),
+	useTags: vi.fn(),
+}));
+
+vi.mock("../client/hooks/blog-hooks", () => hooks);
+
+const CLASS_NAMES = {
+	container: "bg-red-100",
+	postCard: "bg-blue-100",
+	postTitle: "text-purple-700",
+	postMeta: "text-green-600",
+	tagsList: "bg-yellow-50",
+	pagination: "border-4 border-orange-500",
+} as const;
+
+const post: SerializedPost = {
+	id: "p1",
+	title: "Hello World",
+	content: "# Hello",
+	excerpt: "An excerpt",
+	slug: "hello-world",
+	published: true,
+	image: "",
+	tags: [{ id: "t1", name: "Release", slug: "release" }],
+	authorId: null,
+	publishedAt: new Date("2024-01-01").toISOString(),
+	createdAt: new Date("2024-01-01").toISOString(),
+	updatedAt: new Date("2024-01-01").toISOString(),
+} as unknown as SerializedPost;
+
+let container: HTMLDivElement;
+let root: Root;
+
+beforeEach(() => {
+	container = document.createElement("div");
+	document.body.appendChild(container);
+	root = createRoot(container);
+
+	hooks.usePostSearch.mockReturnValue({ data: [], isLoading: false });
+});
+
+afterEach(async () => {
+	await act(async () => {
+		root.unmount();
+	});
+	container.remove();
+	vi.clearAllMocks();
+});
+
+async function render(ui: React.ReactElement) {
+	await act(async () => {
+		root.render(ui);
+	});
+}
+
+function withBlogOverrides(children: React.ReactNode) {
+	return (
+		<StackProvider
+			stack={createTestClientStack({ blog: blogClientPlugin() })}
+			overrides={{
+				blog: {
+					uploadImage: async () => "",
+					classNames: CLASS_NAMES,
+				},
+			}}
+		>
+			{children}
+		</StackProvider>
+	);
+}
+
+function query(selector: string): HTMLElement {
+	const el = container.querySelector<HTMLElement>(selector);
+	expect(el, `expected to find ${selector}`).toBeTruthy();
+	return el!;
+}
+
+describe("blog classNames overrides (issue #36)", () => {
+	it("applies classNames.container to the page container", async () => {
+		await render(
+			withBlogOverrides(
+				<PageWrapper testId="blog-container">
+					<span>content</span>
+				</PageWrapper>,
+			),
+		);
+
+		const el = query('[data-testid="blog-container"]');
+		expect(el.className).toContain(CLASS_NAMES.container);
+		// The override must merge with the layout's own classes, not replace them.
+		expect(el.className).toContain("container");
+		expect(el.className).toContain("mx-auto");
+	});
+
+	it("applies classNames.postCard, postTitle, postMeta and tagsList inside a post card", async () => {
+		await render(withBlogOverrides(<PostsList posts={[post]} />));
+
+		// postCard — anchored on the Card primitive's structural slot.
+		const card = query('[data-slot="card"]');
+		expect(card.className).toContain(CLASS_NAMES.postCard);
+		expect(card.className).toContain("group");
+
+		// postTitle — anchored on the CardTitle primitive's structural slot.
+		const title = query('[data-slot="card-title"]');
+		expect(title.className).toContain(CLASS_NAMES.postTitle);
+		expect(title.className).toContain("line-clamp-3");
+		expect(title.textContent).toBe(post.title);
+
+		// postMeta — the wrapper holding the published date.
+		const meta = query("time").parentElement!;
+		expect(meta.className).toContain(CLASS_NAMES.postMeta);
+		// `cn` runs tailwind-merge, so the conflicting `text-muted-foreground`
+		// is intentionally replaced by the override; non-conflicting base
+		// classes must survive.
+		expect(meta.className).toContain("items-center");
+		expect(meta.className).not.toContain("text-muted-foreground");
+
+		// tagsList — the wrapper immediately following the metadata block.
+		const tags = meta.nextElementSibling as HTMLElement;
+		expect(tags.className).toContain(CLASS_NAMES.tagsList);
+		expect(tags.className).toContain("flex-wrap");
+		expect(tags.textContent).toContain("Release");
+	});
+
+	it("applies classNames.pagination to the load-more wrapper", async () => {
+		await render(
+			withBlogOverrides(
+				<PostsList posts={[post]} onLoadMore={() => {}} hasMore />,
+			),
+		);
+
+		const button = [...container.querySelectorAll("button")].find((b) =>
+			b.textContent?.includes("Load more posts"),
+		);
+		expect(button, "expected a load-more button").toBeTruthy();
+
+		const pagination = button!.parentElement!;
+		expect(pagination.className).toContain("border-4");
+		expect(pagination.className).toContain("border-orange-500");
+		expect(pagination.className).toContain("justify-center");
+	});
+
+	it("leaves base classes untouched when no classNames override is supplied", async () => {
+		await render(
+			<StackProvider
+				stack={createTestClientStack({ blog: blogClientPlugin() })}
+				overrides={{ blog: { uploadImage: async () => "" } }}
+			>
+				<PostsList
+					posts={[
+						{
+							...post,
+							tags: [
+								...post.tags!,
+								{ ...post.tags![0]!, id: "t2", name: "News", slug: "news" },
+							],
+						},
+					]}
+					onLoadMore={() => {}}
+					hasMore
+				/>
+			</StackProvider>,
+		);
+
+		const card = query('[data-slot="card"]');
+		expect(card.className).toContain("group");
+		expect(card.className).not.toContain(CLASS_NAMES.postCard);
+		const metadata = query("time").parentElement!;
+		const tags = metadata.parentElement!.querySelectorAll(
+			'[data-slot="badge"]',
+		);
+		expect(tags).toHaveLength(2);
+		for (const tag of tags) {
+			expect(tag.parentElement).toBe(metadata.parentElement);
+		}
+	});
+});

package/src/plugins/blog/client/components/shared/page-wrapper.tsx

@@ -4,6 +4,7 @@ import { usePluginOverrides } from "@btst/stack/context";
 import { PageWrapper as SharedPageWrapper } from "@workspace/ui/components/page-wrapper";
 import type { BlogPluginOverrides } from "../../overrides";
 import { BLOG_PLUGIN_ID } from "../../constants";
+import { cn } from "../../../utils";
 
 export function PageWrapper({
 	children,
@@ -14,7 +15,7 @@ export function PageWrapper({
 	className?: string;
 	testId?: string;
 }) {
-	const { showAttribution } = usePluginOverrides<
+	const { showAttribution, classNames } = usePluginOverrides<
 		BlogPluginOverrides,
 		Partial<BlogPluginOverrides>
 	>(BLOG_PLUGIN_ID, {
@@ -23,7 +24,7 @@ export function PageWrapper({
 
 	return (
 		<SharedPageWrapper
-			className={className}
+			className={cn(className, classNames?.container)}
 			testId={testId}
 			showAttribution={showAttribution}
 		>