@btst/stack 4.0.0 → 4.1.0

package/src/plugins/blog/client/components/shared/post-card.tsx

@@ -18,7 +18,7 @@ import { CalendarIcon } from "lucide-react";
 import type { BlogPluginOverrides } from "../../overrides";
 import { BLOG_PLUGIN_ID } from "../../constants";
 import { DefaultLink, DefaultImage } from "./defaults";
-
+import { cn } from "../../../utils";
 // Beautiful gradient color combinations
 const GRADIENT_PALETTES = [
 	{
@@ -222,7 +222,7 @@ function getGradientFromTitle(title: string) {
 
 export function PostCard({ post }: { post: SerializedPost }) {
 	const t = useTranslate();
-	const { localization } = usePluginOverrides<
+	const { localization, classNames } = usePluginOverrides<
 		BlogPluginOverrides,
 		Partial<BlogPluginOverrides>
 	>(BLOG_PLUGIN_ID, {});
@@ -234,9 +234,19 @@ export function PostCard({ post }: { post: SerializedPost }) {
 	const timestamp = post.publishedAt || post.createdAt;
 	const postDate = formatPostDate(timestamp);
 	const gradient = post.image ? null : getGradientFromTitle(post.title);
+	const tags = post.tags?.map((tag) => (
+		<Badge key={tag.id} variant="secondary" className="text-xs">
+			{tag.name}
+		</Badge>
+	));
 
 	return (
-		<Card className="group relative flex h-full flex-col gap-4 pt-0! pb-4! transition-shadow duration-200 hover:shadow-lg">
+		<Card
+			className={cn(
+				"group relative flex h-full flex-col gap-4 pt-0! pb-4! transition-shadow duration-200 hover:shadow-lg",
+				classNames?.postCard,
+			)}
+		>
 			{/* Image or Placeholder */}
 			<Link
 				href={blogPath}
@@ -281,24 +291,34 @@ export function PostCard({ post }: { post: SerializedPost }) {
 				className="block focus:outline-none focus-visible:ring-2 focus-visible:ring-ring/50 grow"
 			>
 				<CardHeader className="flex-1">
-					<CardTitle className="line-clamp-3 text-lg leading-tight transition-colors group-hover:underline">
+					<CardTitle
+						className={cn(
+							"line-clamp-3 text-lg leading-tight transition-colors group-hover:underline",
+							classNames?.postTitle,
+						)}
+					>
 						{post.title}
 					</CardTitle>
 				</CardHeader>
 
 				<CardContent className="flex flex-1 flex-col gap-2">
 					<div className="flex flex-wrap gap-2">
-						<div className="flex items-center gap-2 text-muted-foreground text-xs">
+						<div
+							className={cn(
+								"flex items-center gap-2 text-muted-foreground text-xs",
+								classNames?.postMeta,
+							)}
+						>
 							<CalendarIcon className="h-3 w-3" />
 							<time dateTime={timestamp}>{postDate}</time>
 						</div>
-						{post.tags &&
-							post.tags.length > 0 &&
-							post.tags.map((tag) => (
-								<Badge key={tag.id} variant="secondary" className="text-xs">
-									{tag.name}
-								</Badge>
-							))}
+						{classNames?.tagsList ? (
+							<div className={cn("flex flex-wrap gap-2", classNames.tagsList)}>
+								{tags}
+							</div>
+						) : (
+							tags
+						)}
 					</div>
 				</CardContent>
 			</Link>

package/src/plugins/blog/client/components/shared/posts-list.tsx

@@ -6,6 +6,7 @@ import { SearchInput } from "./search-input";
 import type { BlogPluginOverrides } from "../../overrides";
 import { BLOG_PLUGIN_ID } from "../../constants";
 import { PostCard as DefaultPostCard } from "./post-card";
+import { cn } from "../../../utils";
 
 interface PostsListProps {
 	posts: SerializedPost[];
@@ -21,7 +22,7 @@ export function PostsList({
 	isLoadingMore,
 }: PostsListProps) {
 	const t = useTranslate();
-	const { localization, PostCard } =
+	const { localization, PostCard, classNames } =
 		usePluginOverrides<BlogPluginOverrides>(BLOG_PLUGIN_ID);
 
 	const PostCardComponent = PostCard || DefaultPostCard;
@@ -61,7 +62,7 @@ export function PostsList({
 			</div>
 
 			{onLoadMore && hasMore && (
-				<div className="flex justify-center">
+				<div className={cn("flex justify-center", classNames?.pagination)}>
 					<Button
 						onClick={onLoadMore}
 						disabled={isLoadingMore}

package/src/plugins/blog/client/overrides.ts

@@ -41,6 +41,24 @@ export interface BlogPluginOverrides {
 	PostCard?: ComponentType<{
 		post: SerializedPost;
 	}>;
+	/**
+	 * Optional class names merged into the blog UI's structural elements,
+	 * allowing styling without replacing whole components.
+	 */
+	classNames?: {
+		/** Page container shared by blog pages. */
+		container?: string;
+		/** Each built-in post card. */
+		postCard?: string;
+		/** Title inside a post card. */
+		postTitle?: string;
+		/** Date metadata inside a post card. */
+		postMeta?: string;
+		/** Optional flex wrapper around post-card tags; omitted when unset. */
+		tagsList?: string;
+		/** Wrapper around the load-more control. */
+		pagination?: string;
+	};
 	/**
 	 * Function used to upload a new image file and return its URL.
 	 * This is separate from `imagePicker`, which selects an existing asset URL.

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

@@ -0,0 +1,200 @@
+// @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 cms
+// components, which resolve `@btst/stack/*` via package self-reference.
+import { StackProvider } from "@btst/stack/context";
+import { createTestClientStack } from "../../../__tests__/client-stack-test-utils";
+import { cmsClientPlugin } from "../client";
+import { DashboardPage } from "../client/components/pages/dashboard-page.internal";
+import { ContentListPage } from "../client/components/pages/content-list-page.internal";
+import type {
+	SerializedContentItemWithType,
+	SerializedContentType,
+} from "../types";
+
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+// jsdom lacks these APIs used by Radix / cmdk
+(globalThis as any).ResizeObserver ??= class {
+	observe() {}
+	unobserve() {}
+	disconnect() {}
+};
+Element.prototype.scrollIntoView ??= () => {};
+
+const hooks = vi.hoisted(() => ({
+	useContentTypes: vi.fn(),
+	useSuspenseContentTypes: vi.fn(),
+	useContent: vi.fn(),
+	useSuspenseContent: vi.fn(),
+	useDeleteContent: vi.fn(),
+}));
+
+vi.mock("../client/hooks", () => hooks);
+
+const CLASS_NAMES = {
+	container: "bg-red-100",
+	contentTypeCard: "bg-blue-100",
+	contentTypeTitle: "text-purple-700",
+	table: "bg-yellow-50",
+	tableRow: "text-green-600",
+	pagination: "border-4 border-orange-500",
+} as const;
+
+const SIMPLE_JSON_SCHEMA = JSON.stringify({
+	type: "object",
+	properties: { title: { type: "string" } },
+	required: ["title"],
+	autoFormVersion: 2,
+});
+
+const contentType: SerializedContentType & { itemCount: number } = {
+	id: "ct1",
+	name: "Post",
+	slug: "post",
+	description: "",
+	jsonSchema: SIMPLE_JSON_SCHEMA,
+	autoFormVersion: 2,
+	itemCount: 1,
+	createdAt: new Date("2024-01-01").toISOString(),
+	updatedAt: new Date("2024-01-01").toISOString(),
+} as unknown as SerializedContentType & { itemCount: number };
+
+const item: SerializedContentItemWithType = {
+	id: "i1",
+	slug: "hello-world",
+	contentTypeId: "ct1",
+	data: JSON.stringify({ title: "Hello" }),
+	parsedData: { title: "Hello" },
+	contentType: { id: "ct1", name: "Post", slug: "post" },
+	createdAt: new Date("2024-01-01").toISOString(),
+	updatedAt: new Date("2024-01-01").toISOString(),
+	authorId: "user-1",
+} as unknown as SerializedContentItemWithType;
+
+let container: HTMLDivElement;
+let root: Root;
+
+beforeEach(() => {
+	container = document.createElement("div");
+	document.body.appendChild(container);
+	root = createRoot(container);
+
+	hooks.useSuspenseContentTypes.mockReturnValue({
+		contentTypes: [contentType],
+		refetch: vi.fn(),
+	});
+	hooks.useSuspenseContent.mockReturnValue({
+		items: [item],
+		total: 1,
+		loadMore: vi.fn(),
+		hasMore: false,
+		isLoadingMore: false,
+		refetch: vi.fn(),
+	});
+	hooks.useContent.mockReturnValue({
+		items: [],
+		total: 0,
+		isLoading: false,
+		error: null,
+		loadMore: vi.fn(),
+		hasMore: false,
+		isLoadingMore: false,
+	});
+	hooks.useDeleteContent.mockReturnValue({
+		mutateAsync: vi.fn(),
+		isPending: false,
+	});
+});
+
+afterEach(async () => {
+	await act(async () => {
+		root.unmount();
+	});
+	container.remove();
+	vi.clearAllMocks();
+});
+
+function createMockRouter() {
+	let params = new URLSearchParams();
+	return {
+		navigate: vi.fn(),
+		getSearchParams: () => new URLSearchParams(params.toString()),
+		setSearchParams: vi.fn((next: URLSearchParams) => {
+			params = new URLSearchParams(next.toString());
+		}),
+	};
+}
+
+async function render(ui: React.ReactElement, withOverrides = true) {
+	await act(async () => {
+		root.render(
+			<StackProvider
+				stack={createTestClientStack({ cms: cmsClientPlugin() })}
+				router={createMockRouter()}
+				overrides={withOverrides ? { cms: { classNames: CLASS_NAMES } } : {}}
+			>
+				{ui}
+			</StackProvider>,
+		);
+	});
+}
+
+function query(selector: string): HTMLElement {
+	const el = container.querySelector<HTMLElement>(selector);
+	expect(el, `expected to find ${selector}`).toBeTruthy();
+	return el!;
+}
+
+describe("cms classNames overrides (issue #36)", () => {
+	it("applies container, contentTypeCard and contentTypeTitle on the dashboard", async () => {
+		await render(<DashboardPage />);
+
+		const page = query('[data-testid="cms-dashboard-page"]');
+		expect(page.className).toContain(CLASS_NAMES.container);
+		// The override must merge with the layout's own classes, not replace them.
+		expect(page.className).toContain("mx-auto");
+
+		const card = query('[data-slot="card"]');
+		expect(card.className).toContain(CLASS_NAMES.contentTypeCard);
+		expect(card.className).toContain("cursor-pointer");
+
+		const title = query('[data-slot="card-title"]');
+		expect(title.className).toContain(CLASS_NAMES.contentTypeTitle);
+		expect(title.className).toContain("font-medium");
+		expect(title.textContent).toBe(contentType.name);
+	});
+
+	it("applies table, tableRow and pagination on the content list", async () => {
+		await render(<ContentListPage typeSlug="post" />);
+
+		const table = query('[data-testid="cms-content-table"]');
+		expect(table.className).toContain(CLASS_NAMES.table);
+		expect(table.className).toContain("rounded-lg");
+
+		const row = table.querySelector<HTMLElement>("tbody tr")!;
+		expect(row, "expected a body row").toBeTruthy();
+		expect(row.className).toContain(CLASS_NAMES.tableRow);
+		expect(row.textContent).toContain(item.slug);
+
+		const pagination = query('[data-testid="cms-content-pagination"]');
+		expect(pagination.className).toContain("border-4");
+		expect(pagination.className).toContain("border-orange-500");
+		// Non-conflicting base classes survive the merge. (`border-t` is
+		// intentionally dropped by tailwind-merge since `border-4` wins the
+		// border-width group — that is the override taking precedence.)
+		expect(pagination.className).toContain("justify-between");
+		expect(pagination.className).toContain("px-4");
+	});
+
+	it("leaves base classes untouched when no classNames override is supplied", async () => {
+		await render(<DashboardPage />, false);
+
+		const card = query('[data-slot="card"]');
+		expect(card.className).toContain("cursor-pointer");
+		expect(card.className).not.toContain(CLASS_NAMES.contentTypeCard);
+	});
+});

package/src/plugins/cms/client/components/pages/content-list-page.internal.tsx

@@ -25,6 +25,7 @@ import { cmsPermissions } from "../../../permissions";
 import { useListState, type ListStateSchema } from "@btst/stack/client/hooks";
 import { orderCMSContentTypes, type CMSPluginOverrides } from "../../overrides";
 import { CMS_PLUGIN_ID } from "../../constants";
+import { cn } from "../../../utils";
 import type { SerializedContentItemWithType } from "../../../types";
 import {
 	useContent,
@@ -52,7 +53,7 @@ export function ContentListPage({ typeSlug }: ContentListPageProps) {
 	const t = useTranslate();
 	const notify = useNotify();
 	const overrides = usePluginOverrides<CMSPluginOverrides>(CMS_PLUGIN_ID);
-	const { localization } = overrides;
+	const { localization, classNames } = overrides;
 	const { router, plugins, basePath: stackBasePath } = useStack();
 	const navigate = router?.navigate;
 	const Link = router?.Link;
@@ -287,6 +288,7 @@ export function ContentListPage({ typeSlug }: ContentListPageProps) {
 						hasMore={hasMore}
 						isLoadingMore={isLoadingMore}
 						localization={localization}
+						classNames={classNames}
 						t={t}
 					/>
 				)}
@@ -309,6 +311,7 @@ function ContentTable({
 	hasMore,
 	isLoadingMore,
 	localization,
+	classNames,
 	t,
 }: {
 	items: SerializedContentItemWithType[];
@@ -324,10 +327,14 @@ function ContentTable({
 	hasMore: boolean;
 	isLoadingMore: boolean;
 	localization: CMSPluginOverrides["localization"];
+	classNames: CMSPluginOverrides["classNames"];
 	t: TranslateFn;
 }) {
 	return (
-		<div className="border rounded-lg">
+		<div
+			className={cn("border rounded-lg", classNames?.table)}
+			data-testid="cms-content-table"
+		>
 			<Table>
 				<TableHeader>
 					<TableRow>
@@ -351,7 +358,7 @@ function ContentTable({
 				</TableHeader>
 				<TableBody>
 					{items.map((item) => (
-						<TableRow key={item.id}>
+						<TableRow key={item.id} className={classNames?.tableRow}>
 							<TableCell className="font-medium">
 								<LinkComponent
 									href={joinBasePath(basePath, `/cms/${typeSlug}/${item.id}`)}
@@ -406,7 +413,13 @@ function ContentTable({
 				</TableBody>
 			</Table>
 			{/* Load More and pagination info */}
-			<div className="flex items-center justify-between px-4 py-3 border-t">
+			<div
+				className={cn(
+					"flex items-center justify-between px-4 py-3 border-t",
+					classNames?.pagination,
+				)}
+				data-testid="cms-content-pagination"
+			>
 				<p className="text-sm text-muted-foreground">
 					{(
 						localization?.CMS_LIST_PAGINATION_SHOWING ??

package/src/plugins/cms/client/components/pages/dashboard-page.internal.tsx

@@ -19,11 +19,12 @@ import { useSuspenseContentTypes } from "../../hooks";
 import { EmptyState } from "../shared/empty-state";
 import { PageWrapper } from "../shared/page-wrapper";
 import { useRouteLifecycle } from "@workspace/ui/hooks/use-route-lifecycle";
+import { cn } from "../../../utils";
 
 export function DashboardPage() {
 	const t = useTranslate();
 	const overrides = usePluginOverrides<CMSPluginOverrides>(CMS_PLUGIN_ID);
-	const { localization } = overrides;
+	const { localization, classNames } = overrides;
 	const { router, plugins, basePath: stackBasePath } = useStack();
 	const navigate = router?.navigate;
 	const basePath = plugins?.[CMS_PLUGIN_ID]?.site.basePath ?? stackBasePath;
@@ -104,13 +105,23 @@ export function DashboardPage() {
 					{contentTypes.map((ct) => (
 						<Card
 							key={ct.id}
-							className="hover:border-primary/50 transition-colors cursor-pointer"
+							className={cn(
+								"hover:border-primary/50 transition-colors cursor-pointer",
+								classNames?.contentTypeCard,
+							)}
 							onClick={() =>
 								void navigate?.(joinBasePath(basePath, `/cms/${ct.slug}`))
 							}
 						>
 							<CardHeader className="flex flex-row items-center justify-between space-y-0 pb-2">
-								<CardTitle className="text-lg font-medium">{ct.name}</CardTitle>
+								<CardTitle
+									className={cn(
+										"text-lg font-medium",
+										classNames?.contentTypeTitle,
+									)}
+								>
+									{ct.name}
+								</CardTitle>
 								<FileText className="h-5 w-5 text-muted-foreground" />
 							</CardHeader>
 							<CardContent>

package/src/plugins/cms/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 { CMSPluginOverrides } from "../../overrides";
 import { CMS_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<
 		CMSPluginOverrides,
 		Partial<CMSPluginOverrides>
 	>(CMS_PLUGIN_ID, {
@@ -23,7 +24,7 @@ export function PageWrapper({
 
 	return (
 		<SharedPageWrapper
-			className={className}
+			className={cn(className, classNames?.container)}
 			testId={testId}
 			showAttribution={showAttribution}
 		>

package/src/plugins/cms/client/overrides.ts

@@ -129,6 +129,25 @@ export interface CMSPluginOverrides {
 	 */
 	imagePicker?: ComponentType<{ onSelect: (url: string) => void }>;
 
+	/**
+	 * Optional class names merged onto specific UI elements.
+	 * Use these for targeted styling without replacing whole components.
+	 */
+	classNames?: {
+		/** Page container shared by every CMS page */
+		container?: string;
+		/** Each content-type card on the dashboard */
+		contentTypeCard?: string;
+		/** Title inside a content-type card */
+		contentTypeTitle?: string;
+		/** Wrapper around the content entries table */
+		table?: string;
+		/** Each row in the content entries table */
+		tableRow?: string;
+		/** Pagination footer under the content entries table */
+		pagination?: string;
+	};
+
 	/**
 	 * Custom field components for AutoForm fields.
 	 *