@btst/stack 4.0.0 → 4.1.1

package/src/plugins/form-builder/__tests__/classnames-overrides.test.tsx

@@ -0,0 +1,312 @@
+// @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 { z } from "zod";
+// Core primitives MUST be imported from the package entry (not relative src
+// paths) so they share module identity — and React context — with the
+// form-builder components, which resolve `@btst/stack/*` via package
+// self-reference.
+import { StackProvider } from "@btst/stack/context";
+import { defineAuthorization } from "@btst/stack/authorization";
+import { createClientAuth } from "@btst/stack/authorization/client";
+import { FormRenderer } from "../client/components/forms/form-renderer";
+import { FormListPage } from "../client/components/pages/form-list-page.internal";
+import { SubmissionsPage } from "../client/components/pages/submissions-page.internal";
+import { formBuilderClientPlugin } from "../client/plugin";
+import { formBuilderPermissions } from "../permissions";
+import type { SerializedForm } from "../types";
+import { createTestClientStack } from "../../../__tests__/client-stack-test-utils";
+
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+// jsdom lacks these APIs used by Radix
+(globalThis as any).ResizeObserver ??= class {
+	observe() {}
+	unobserve() {}
+	disconnect() {}
+};
+Element.prototype.scrollIntoView ??= () => {};
+
+const listHooks = vi.hoisted(() => ({
+	useForms: vi.fn(),
+	useSuspenseForms: vi.fn(),
+	useDeleteForm: vi.fn(),
+	useSuspenseFormById: vi.fn(),
+	useSuspenseFormForUpdate: vi.fn(),
+	useSuspenseSubmissions: vi.fn(),
+	useSubmission: vi.fn(),
+	useDeleteSubmission: vi.fn(),
+	useFormBuilderForm: vi.fn(),
+}));
+const rendererHooks = vi.hoisted(() => ({
+	useFormBySlug: vi.fn(),
+	useSubmitForm: vi.fn(),
+}));
+
+vi.mock("../client/hooks", () => listHooks);
+vi.mock("../client/hooks/form-builder-hooks", () => rendererHooks);
+
+// The auto-form internals are unrelated to class wiring — stub them.
+vi.mock("@workspace/ui/components/auto-form/stepped-auto-form", () => ({
+	SteppedAutoForm: ({
+		onSubmit,
+	}: {
+		onSubmit: (values: Record<string, unknown>) => void;
+	}) => (
+		<button
+			type="button"
+			data-testid="stepped-auto-form"
+			onClick={() => onSubmit({})}
+		>
+			Submit
+		</button>
+	),
+}));
+
+const CLASS_NAMES = {
+	container: "bg-red-100",
+	table: "bg-yellow-50",
+	tableRow: "text-green-600",
+	pagination: "border-4 border-orange-500",
+	form: "bg-blue-100",
+} as const;
+
+const form: SerializedForm = {
+	id: "f1",
+	name: "Contact Form",
+	slug: "contact-form",
+	description: null,
+	schema: JSON.stringify({ type: "object", properties: {} }),
+	successMessage: null,
+	redirectUrl: null,
+	status: "active",
+	createdBy: null,
+	createdAt: new Date("2024-01-01").toISOString(),
+	updatedAt: new Date("2024-01-01").toISOString(),
+} as unknown as SerializedForm;
+
+const authorization = defineAuthorization({
+	identity: z.object({ id: z.string(), role: z.string() }),
+	permissions: [formBuilderPermissions] as const,
+	rules: ({ forms }) => [
+		forms.form.render.allow(),
+		forms.submission.create.allow(),
+		forms.submission.read.allow(),
+	],
+});
+const auth = createClientAuth({ authorization, getIdentity: () => null });
+
+let container: HTMLDivElement;
+let root: Root;
+
+beforeEach(() => {
+	container = document.createElement("div");
+	document.body.appendChild(container);
+	root = createRoot(container);
+
+	listHooks.useSuspenseForms.mockReturnValue({
+		forms: [form],
+		total: 1,
+		loadMore: vi.fn(),
+		hasMore: false,
+		isLoadingMore: false,
+		refetch: vi.fn(),
+	});
+	listHooks.useForms.mockReturnValue({
+		forms: [],
+		total: 0,
+		isLoading: false,
+		error: null,
+		loadMore: vi.fn(),
+		hasMore: false,
+		isLoadingMore: false,
+		refetch: vi.fn(),
+	});
+	listHooks.useDeleteForm.mockReturnValue({
+		mutateAsync: vi.fn(),
+		isPending: false,
+	});
+	rendererHooks.useFormBySlug.mockReturnValue({
+		form,
+		isLoading: false,
+		error: null,
+	});
+	rendererHooks.useSubmitForm.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({
+					formBuilder: formBuilderClientPlugin(),
+				})}
+				router={createMockRouter()}
+				auth={auth}
+				initialIdentity={null}
+				overrides={
+					withOverrides ? { formBuilder: { 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("form-builder classNames overrides (issue #36)", () => {
+	it("applies container, table, tableRow and pagination on the forms list", async () => {
+		await render(<FormListPage />);
+
+		const page = query('[data-testid="form-list-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 table = query('[data-testid="form-builder-list-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(form.name);
+
+		const pagination = query('[data-testid="form-builder-pagination"]');
+		expect(pagination.className).toContain("border-4");
+		expect(pagination.className).toContain("border-orange-500");
+		expect(pagination.className).toContain("justify-between");
+	});
+
+	it("applies table, tableRow and pagination on the submissions page", async () => {
+		listHooks.useSuspenseSubmissions.mockReturnValue({
+			form,
+			submissions: [
+				{
+					id: "sub-11111111",
+					formId: form.id,
+					submittedAt: new Date("2024-01-02").toISOString(),
+				},
+			],
+			total: 1,
+			loadMore: vi.fn(),
+			hasMore: false,
+			isLoadingMore: false,
+			refetch: vi.fn(),
+		});
+		listHooks.useSubmission.mockReturnValue({
+			submission: null,
+			isLoading: false,
+			error: null,
+			refetch: vi.fn(),
+		});
+		listHooks.useDeleteSubmission.mockReturnValue({
+			mutateAsync: vi.fn(),
+			isPending: false,
+		});
+
+		await render(<SubmissionsPage formId={form.id} />);
+
+		const table = query('[data-testid="form-builder-submissions-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);
+
+		const pagination = query('[data-testid="form-builder-pagination"]');
+		expect(pagination.className).toContain("border-orange-500");
+		expect(pagination.className).toContain("justify-between");
+	});
+
+	it("applies classNames.form to the rendered public form", async () => {
+		await render(<FormRenderer slug={form.slug} />);
+
+		const root = query('[data-testid="form-renderer"]');
+		expect(root.className).toContain(CLASS_NAMES.form);
+		// The real auto-form is stubbed, but it must still be mounted inside the slot.
+		expect(
+			root.querySelector('[data-testid="stepped-auto-form"]'),
+		).toBeTruthy();
+	});
+
+	it.each([
+		["loading", { form: null, isLoading: true, error: null }],
+		[
+			"error",
+			{ form: null, isLoading: false, error: new Error("Unavailable") },
+		],
+		["not found", { form: null, isLoading: false, error: null }],
+		[
+			"inactive",
+			{ form: { ...form, status: "inactive" }, isLoading: false, error: null },
+		],
+		[
+			"invalid schema",
+			{ form: { ...form, schema: "invalid" }, isLoading: false, error: null },
+		],
+	])("preserves form classes in the %s state", async (_state, result) => {
+		rendererHooks.useFormBySlug.mockReturnValue(result);
+		await render(<FormRenderer slug={form.slug} className="p-6" />);
+		const wrapper = container.firstElementChild!;
+		expect(wrapper.className).toContain(CLASS_NAMES.form);
+		expect(wrapper.className).toContain("p-6");
+	});
+
+	it("preserves form classes after successful submission", async () => {
+		const submit = vi
+			.fn()
+			.mockResolvedValue({ form: { successMessage: "Thank you!" } });
+		rendererHooks.useSubmitForm.mockReturnValue({
+			mutateAsync: submit,
+			isPending: false,
+		});
+		await render(<FormRenderer slug={form.slug} className="p-6" />);
+		await act(async () => {
+			query('[data-testid="stepped-auto-form"]').click();
+		});
+		expect(submit).toHaveBeenCalled();
+		expect(container.textContent).toContain("Thank you!");
+		const wrapper = container.firstElementChild!;
+		expect(wrapper.className).toContain(CLASS_NAMES.form);
+		expect(wrapper.className).toContain("p-6");
+	});
+
+	it("leaves base classes untouched when no classNames override is supplied", async () => {
+		await render(<FormListPage />, false);
+
+		const table = query('[data-testid="form-builder-list-table"]');
+		expect(table.className).toContain("rounded-lg");
+		expect(table.className).not.toContain(CLASS_NAMES.table);
+	});
+});

package/src/plugins/form-builder/client/components/forms/form-renderer.tsx

@@ -18,6 +18,7 @@ import type { FormBuilderPluginOverrides } from "../../overrides";
 import type { SerializedFormSubmission } from "../../../types";
 import { formBuilderPermissions } from "../../../permissions";
 import { FORM_BUILDER_PLUGIN_ID } from "../../constants";
+import { cn } from "../../../utils";
 
 export interface FormRendererProps {
 	/** Form slug to render */
@@ -132,9 +133,13 @@ export function FormRenderer({
 	className,
 }: FormRendererProps) {
 	const t = useTranslate();
-	const { fieldComponents: overrideFieldComponents, localization } =
-		usePluginOverrides<FormBuilderPluginOverrides>(FORM_BUILDER_PLUGIN_ID);
+	const {
+		fieldComponents: overrideFieldComponents,
+		localization,
+		classNames,
+	} = usePluginOverrides<FormBuilderPluginOverrides>(FORM_BUILDER_PLUGIN_ID);
 
+	const formClassName = cn(className, classNames?.form);
 	const { form, isLoading, error } = useFormBySlug(slug);
 	const submitMutation = useSubmitForm(slug);
 
@@ -201,7 +206,7 @@ export function FormRenderer({
 	// Loading state
 	if (isLoading) {
 		return (
-			<div className={className}>
+			<div className={formClassName}>
 				<LoadingComponent />
 			</div>
 		);
@@ -210,7 +215,7 @@ export function FormRenderer({
 	// Error state
 	if (error) {
 		return (
-			<div className={className}>
+			<div className={formClassName}>
 				<ErrorComponent error={error} />
 			</div>
 		);
@@ -219,7 +224,7 @@ export function FormRenderer({
 	// Form not found
 	if (!form) {
 		return (
-			<div className={className}>
+			<div className={formClassName}>
 				<ErrorComponent
 					error={
 						new Error(
@@ -235,7 +240,7 @@ export function FormRenderer({
 	// Form not active
 	if (form.status !== "active") {
 		return (
-			<div className={className}>
+			<div className={formClassName}>
 				<ErrorComponent
 					error={
 						new Error(
@@ -254,7 +259,7 @@ export function FormRenderer({
 	// Schema parsing failed
 	if (!zodSchema) {
 		return (
-			<div className={className}>
+			<div className={formClassName}>
 				<ErrorComponent
 					error={
 						new Error(
@@ -273,7 +278,7 @@ export function FormRenderer({
 	// Success state
 	if (submitted && finalSuccessMessage) {
 		return (
-			<div className={className}>
+			<div className={formClassName}>
 				<DefaultSuccessComponent message={finalSuccessMessage} />
 			</div>
 		);
@@ -300,7 +305,7 @@ export function FormRenderer({
 					status: form.status,
 				})}
 			>
-				<div className={className} data-testid="form-renderer">
+				<div className={formClassName} data-testid="form-renderer">
 					<SteppedAutoForm
 						formSchema={zodSchema}
 						fieldConfig={fieldConfig}

package/src/plugins/form-builder/client/components/pages/form-list-page.internal.tsx

@@ -52,6 +52,7 @@ import { EmptyState } from "../shared/empty-state";
 import { Pagination } from "../shared/pagination";
 import { formBuilderPermissions } from "../../../permissions";
 import { FORM_BUILDER_PLUGIN_ID } from "../../constants";
+import { cn } from "../../../utils";
 
 // URL-synced search state: `?q=...` while typing (history: replace), clean
 // URL when the query is empty (the default is omitted from the URL).
@@ -64,9 +65,8 @@ const SEARCH_DEBOUNCE_MS = 300;
 export function FormListPage() {
 	const t = useTranslate();
 	const notify = useNotify();
-	const { localization } = usePluginOverrides<FormBuilderPluginOverrides>(
-		FORM_BUILDER_PLUGIN_ID,
-	);
+	const { localization, classNames } =
+		usePluginOverrides<FormBuilderPluginOverrides>(FORM_BUILDER_PLUGIN_ID);
 	const { Link, navigate, resolve } = usePluginSiteNavigation(
 		FORM_BUILDER_PLUGIN_ID,
 	);
@@ -233,7 +233,10 @@ export function FormListPage() {
 					)
 				) : (
 					<>
-						<div className="rounded-lg border">
+						<div
+							className={cn("rounded-lg border", classNames?.table)}
+							data-testid="form-builder-list-table"
+						>
 							<Table>
 								<TableHeader>
 									<TableRow>
@@ -261,7 +264,7 @@ export function FormListPage() {
 								</TableHeader>
 								<TableBody>
 									{forms.map((form) => (
-										<TableRow key={form.id}>
+										<TableRow key={form.id} className={classNames?.tableRow}>
 											<TableCell className="font-medium">{form.name}</TableCell>
 											<TableCell className="text-muted-foreground font-mono text-sm">
 												{form.slug}
@@ -362,6 +365,7 @@ export function FormListPage() {
 							hasMore={hasMore}
 							isLoadingMore={isLoadingMore}
 							onLoadMore={loadMore}
+							className={classNames?.pagination}
 							labels={{
 								showing:
 									localization?.FORM_BUILDER_LIST_PAGINATION_SHOWING ??

package/src/plugins/form-builder/client/components/pages/submissions-page.internal.tsx

@@ -48,6 +48,7 @@ import { EmptyState } from "../shared/empty-state";
 import { Pagination } from "../shared/pagination";
 import { formBuilderPermissions } from "../../../permissions";
 import { FORM_BUILDER_PLUGIN_ID } from "../../constants";
+import { cn } from "../../../utils";
 
 export interface SubmissionsPageProps {
 	formId: string;
@@ -56,9 +57,8 @@ export interface SubmissionsPageProps {
 export function SubmissionsPage({ formId }: SubmissionsPageProps) {
 	const t = useTranslate();
 	const notify = useNotify();
-	const { localization } = usePluginOverrides<FormBuilderPluginOverrides>(
-		FORM_BUILDER_PLUGIN_ID,
-	);
+	const { localization, classNames } =
+		usePluginOverrides<FormBuilderPluginOverrides>(FORM_BUILDER_PLUGIN_ID);
 	const { identity } = useIdentity();
 	const { Link: LinkComponent, resolve } = usePluginSiteNavigation(
 		FORM_BUILDER_PLUGIN_ID,
@@ -143,7 +143,10 @@ export function SubmissionsPage({ formId }: SubmissionsPageProps) {
 					/>
 				) : (
 					<>
-						<div className="rounded-lg border">
+						<div
+							className={cn("rounded-lg border", classNames?.table)}
+							data-testid="form-builder-submissions-table"
+						>
 							<Table>
 								<TableHeader>
 									<TableRow>
@@ -166,7 +169,7 @@ export function SubmissionsPage({ formId }: SubmissionsPageProps) {
 								</TableHeader>
 								<TableBody>
 									{submissions.map((sub) => (
-										<TableRow key={sub.id}>
+										<TableRow key={sub.id} className={classNames?.tableRow}>
 											<TableCell className="font-mono text-xs">
 												{sub.id.slice(0, 8)}...
 											</TableCell>
@@ -249,6 +252,7 @@ export function SubmissionsPage({ formId }: SubmissionsPageProps) {
 							hasMore={hasMore}
 							isLoadingMore={isLoadingMore}
 							onLoadMore={loadMore}
+							className={classNames?.pagination}
 							labels={{
 								showing:
 									localization?.FORM_BUILDER_LIST_PAGINATION_SHOWING ??

package/src/plugins/form-builder/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 { FormBuilderPluginOverrides } from "../../overrides";
 import { FORM_BUILDER_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<
 		FormBuilderPluginOverrides,
 		Partial<FormBuilderPluginOverrides>
 	>(FORM_BUILDER_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/form-builder/client/components/shared/pagination.tsx

@@ -2,6 +2,7 @@
 
 import { Button } from "@workspace/ui/components/button";
 import { ChevronRight } from "lucide-react";
+import { cn } from "../../../utils";
 
 interface PaginationProps {
 	total: number;
@@ -9,6 +10,7 @@ interface PaginationProps {
 	hasMore: boolean;
 	isLoadingMore: boolean;
 	onLoadMore: () => void;
+	className?: string;
 	labels?: {
 		showing?: string;
 		previous?: string;
@@ -23,6 +25,7 @@ export function Pagination({
 	hasMore,
 	isLoadingMore,
 	onLoadMore,
+	className,
 	labels = {},
 }: PaginationProps) {
 	const {
@@ -36,7 +39,10 @@ export function Pagination({
 		.replace("{total}", String(total));
 
 	return (
-		<div className="flex items-center justify-between py-4">
+		<div
+			className={cn("flex items-center justify-between py-4", className)}
+			data-testid="form-builder-pagination"
+		>
 			<p className="text-sm text-muted-foreground">{showingText}</p>
 			{hasMore && (
 				<Button

package/src/plugins/form-builder/client/overrides.ts

@@ -51,6 +51,23 @@ export interface FormBuilderPluginOverrides {
 	 */
 	fieldComponents?: Record<string, ComponentType<AutoFormInputComponentProps>>;
 
+	/**
+	 * Optional class names merged onto specific UI elements.
+	 * Use these for targeted styling without replacing whole components.
+	 */
+	classNames?: {
+		/** Page container shared by every Form Builder page */
+		container?: string;
+		/** Wrapper around the forms or submissions table */
+		table?: string;
+		/** Each body row in the forms or submissions table */
+		tableRow?: string;
+		/** Pagination footer under the forms or submissions list */
+		pagination?: string;
+		/** Root of `FormRenderer`, including loading, error, and success states */
+		form?: string;
+	};
+
 	/**
 	 * Localization object for the Form Builder plugin
 	 */