@btst/stack 1.5.2 → 1.6.0

package/dist/shared/stack.DzH_wcvr.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Form Builder Plugin Types
+ *
+ * Key distinction from CMS Plugin:
+ * - CMS uses developer-defined Zod schemas in code
+ * - Form Builder allows non-technical admins to build forms via drag-and-drop UI
+ * - Forms are serialized to/from JSON Schema for storage
+ */
+/**
+ * Form stored in the database
+ */
+type Form = {
+    id: string;
+    /** Display name for the form */
+    name: string;
+    /** URL-friendly slug - unique identifier for public access */
+    slug: string;
+    /** Optional description for admin UI */
+    description?: string;
+    /** JSON Schema stored as string (includes steps, fieldType, stepGroup, etc.) */
+    schema: string;
+    /** Optional custom success message after submission */
+    successMessage?: string;
+    /** Optional redirect URL after submission */
+    redirectUrl?: string;
+    /** Form status: active, inactive, archived */
+    status: "active" | "inactive" | "archived";
+    /** User who created the form */
+    createdBy?: string;
+    createdAt: Date;
+    updatedAt: Date;
+};
+/**
+ * Form submission stored in the database
+ */
+type FormSubmission = {
+    id: string;
+    /** Reference to the form */
+    formId: string;
+    /** Submitted data as JSON string */
+    data: string;
+    /** Submission timestamp */
+    submittedAt: Date;
+    /** Optional user ID if authenticated */
+    submittedBy?: string;
+    /** Client IP address for rate limiting and spam protection */
+    ipAddress?: string;
+    /** User agent for analytics */
+    userAgent?: string;
+};
+/**
+ * Serialized form for API responses (dates as strings)
+ */
+interface SerializedForm extends Omit<Form, "createdAt" | "updatedAt" | "status"> {
+    status: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Serialized form submission for API responses (dates as strings)
+ */
+interface SerializedFormSubmission extends Omit<FormSubmission, "submittedAt"> {
+    submittedAt: string;
+}
+/**
+ * Serialized form submission with parsed data
+ */
+interface SerializedFormSubmissionWithData<TData = Record<string, unknown>> extends SerializedFormSubmission {
+    /** Parsed data object (JSON.parse of data field) */
+    parsedData: TData;
+    /** Joined form */
+    form?: SerializedForm;
+}
+/**
+ * Paginated list response for forms
+ */
+interface PaginatedForms {
+    items: SerializedForm[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+/**
+ * Paginated list response for form submissions
+ */
+interface PaginatedFormSubmissions<TData = Record<string, unknown>> {
+    items: SerializedFormSubmissionWithData<TData>[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+/**
+ * Context passed to all backend hooks
+ */
+interface FormBuilderHookContext {
+    /** User ID if authenticated */
+    userId?: string;
+    /** Request headers */
+    headers?: Headers;
+    /** Client IP address (for rate limiting) */
+    ipAddress?: string;
+    /** User agent string */
+    userAgent?: string;
+}
+/**
+ * Context for submission-specific hooks
+ */
+interface SubmissionHookContext extends FormBuilderHookContext {
+    /** Form slug being submitted */
+    formSlug: string;
+    /** Form ID */
+    formId: string;
+}
+/**
+ * Input data for creating a form
+ */
+interface FormInput {
+    name: string;
+    slug: string;
+    description?: string;
+    schema: string;
+    successMessage?: string;
+    redirectUrl?: string;
+    status?: "active" | "inactive" | "archived";
+    createdBy?: string;
+}
+/**
+ * Input data for updating a form
+ */
+interface FormUpdate {
+    name?: string;
+    slug?: string;
+    description?: string;
+    schema?: string;
+    successMessage?: string;
+    redirectUrl?: string;
+    status?: "active" | "inactive" | "archived";
+}
+/**
+ * Backend hooks for Form Builder plugin
+ *
+ * All CRUD hooks receive ipAddress and headers for auth/rate limiting.
+ * Return false from onBefore* hooks to reject the operation (throws 403).
+ */
+interface FormBuilderBackendHooks {
+    /** Called before listing forms. Return false to deny access (403). */
+    onBeforeListForms?: (ctx: FormBuilderHookContext) => Promise<boolean> | boolean;
+    /** Called before creating a form. Return false to deny, or modified data. */
+    onBeforeFormCreated?: (data: FormInput, ctx: FormBuilderHookContext) => Promise<FormInput | false> | FormInput | false;
+    /** Called after a form is created */
+    onAfterFormCreated?: (form: SerializedForm, ctx: FormBuilderHookContext) => Promise<void> | void;
+    /** Called before getting a form by ID or slug. Return false to deny access. */
+    onBeforeGetForm?: (idOrSlug: string, ctx: FormBuilderHookContext) => Promise<boolean> | boolean;
+    /** Called before updating a form. Return false to deny, or modified data. */
+    onBeforeFormUpdated?: (id: string, data: FormUpdate, ctx: FormBuilderHookContext) => Promise<FormUpdate | false> | FormUpdate | false;
+    /** Called after a form is updated */
+    onAfterFormUpdated?: (form: SerializedForm, ctx: FormBuilderHookContext) => Promise<void> | void;
+    /** Called before deleting a form. Return false to deny. */
+    onBeforeFormDeleted?: (id: string, ctx: FormBuilderHookContext) => Promise<boolean> | boolean;
+    /** Called after a form is deleted */
+    onAfterFormDeleted?: (id: string, ctx: FormBuilderHookContext) => Promise<void> | void;
+    /**
+     * Called before processing a form submission.
+     * Use for: spam protection, rate limiting, data validation/enrichment.
+     *
+     * @returns false to reject submission (400), or modified data to continue
+     */
+    onBeforeSubmission?: (formSlug: string, data: Record<string, unknown>, ctx: SubmissionHookContext) => Promise<Record<string, unknown> | false> | Record<string, unknown> | false;
+    /**
+     * Called after a submission is saved.
+     * Use for: sending emails, storing in CRM, triggering workflows.
+     */
+    onAfterSubmission?: (submission: SerializedFormSubmission, form: SerializedForm, ctx: SubmissionHookContext) => Promise<void> | void;
+    /** Called when a submission fails */
+    onSubmissionError?: (error: Error, formSlug: string, data: Record<string, unknown>, ctx: SubmissionHookContext) => Promise<void> | void;
+    /** Called before listing submissions. Return false to deny access (403). */
+    onBeforeListSubmissions?: (formId: string, ctx: FormBuilderHookContext) => Promise<boolean> | boolean;
+    /** Called before getting a submission. Return false to deny access. */
+    onBeforeGetSubmission?: (submissionId: string, ctx: FormBuilderHookContext) => Promise<boolean> | boolean;
+    /** Called before deleting a submission. Return false to deny. */
+    onBeforeSubmissionDeleted?: (submissionId: string, ctx: FormBuilderHookContext) => Promise<boolean> | boolean;
+    /** Called after a submission is deleted */
+    onAfterSubmissionDeleted?: (submissionId: string, ctx: FormBuilderHookContext) => Promise<void> | void;
+    /** Called on any error */
+    onError?: (error: Error, operation: "list" | "get" | "create" | "update" | "delete" | "submit" | "listSubmissions" | "getSubmission" | "deleteSubmission", ctx: FormBuilderHookContext) => Promise<void> | void;
+}
+/**
+ * Configuration for the Form Builder backend plugin
+ */
+interface FormBuilderBackendConfig {
+    /** Optional hooks for customizing behavior */
+    hooks?: FormBuilderBackendHooks;
+}
+
+export type { FormBuilderBackendConfig as F, PaginatedForms as P, SerializedForm as S, SerializedFormSubmission as a, SerializedFormSubmissionWithData as b, PaginatedFormSubmissions as c };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btst/stack",
-  "version": "1.5.2",
+  "version": "1.6.0",
   "description": "A composable, plugin-based library for building full-stack applications.",
   "repository": {
     "type": "git",
@@ -206,6 +206,47 @@
       }
     },
     "./plugins/cms/css": "./dist/plugins/cms/style.css",
+    "./plugins/form-builder/api": {
+      "import": {
+        "types": "./dist/plugins/form-builder/api/index.d.ts",
+        "default": "./dist/plugins/form-builder/api/index.mjs"
+      },
+      "require": {
+        "types": "./dist/plugins/form-builder/api/index.d.cts",
+        "default": "./dist/plugins/form-builder/api/index.cjs"
+      }
+    },
+    "./plugins/form-builder/client": {
+      "import": {
+        "types": "./dist/plugins/form-builder/client/index.d.ts",
+        "default": "./dist/plugins/form-builder/client/index.mjs"
+      },
+      "require": {
+        "types": "./dist/plugins/form-builder/client/index.d.cts",
+        "default": "./dist/plugins/form-builder/client/index.cjs"
+      }
+    },
+    "./plugins/form-builder/client/components": {
+      "import": {
+        "types": "./dist/plugins/form-builder/client/components/index.d.ts",
+        "default": "./dist/plugins/form-builder/client/components/index.mjs"
+      },
+      "require": {
+        "types": "./dist/plugins/form-builder/client/components/index.d.cts",
+        "default": "./dist/plugins/form-builder/client/components/index.cjs"
+      }
+    },
+    "./plugins/form-builder/client/hooks": {
+      "import": {
+        "types": "./dist/plugins/form-builder/client/hooks/index.d.ts",
+        "default": "./dist/plugins/form-builder/client/hooks/index.mjs"
+      },
+      "require": {
+        "types": "./dist/plugins/form-builder/client/hooks/index.d.cts",
+        "default": "./dist/plugins/form-builder/client/hooks/index.cjs"
+      }
+    },
+    "./plugins/form-builder/css": "./dist/plugins/form-builder/style.css",
     "./dist/*": "./dist/*",
     "./ui/css": "./dist/ui/components.css",
     "./package.json": "./package.json"
@@ -259,6 +300,18 @@
       ],
       "plugins/cms/client/hooks": [
         "./dist/plugins/cms/client/hooks/index.d.ts"
+      ],
+      "plugins/form-builder/api": [
+        "./dist/plugins/form-builder/api/index.d.ts"
+      ],
+      "plugins/form-builder/client": [
+        "./dist/plugins/form-builder/client/index.d.ts"
+      ],
+      "plugins/form-builder/client/components": [
+        "./dist/plugins/form-builder/client/components/index.d.ts"
+      ],
+      "plugins/form-builder/client/hooks": [
+        "./dist/plugins/form-builder/client/hooks/index.d.ts"
       ]
     }
   },

package/src/plugins/cms/api/plugin.ts

@@ -2,6 +2,10 @@ import type { Adapter } from "@btst/db";
 import { defineBackendPlugin } from "@btst/stack/plugins/api";
 import { createEndpoint } from "@btst/stack/plugins/api";
 import { z } from "zod";
+import {
+	zodToFormSchema,
+	formSchemaToZod,
+} from "@workspace/ui/lib/schema-converter";
 import { cmsSchema as dbSchema } from "../db";
 import type {
 	ContentType,
@@ -124,8 +128,9 @@ async function syncContentTypes(
 	config: CMSBackendConfig,
 ): Promise<void> {
 	for (const ct of config.contentTypes) {
-		// Convert Zod schema to JSON Schema - fieldType is now embedded via .meta()
-		const jsonSchema = JSON.stringify(z.toJSONSchema(ct.schema));
+		// Convert Zod schema to JSON Schema using zodToFormSchema
+		// This properly handles dates, date constraints, and steps metadata
+		const jsonSchema = JSON.stringify(zodToFormSchema(ct.schema));
 
 		const existing = await adapter.findOne<ContentType>({
 			model: "contentType",
@@ -184,11 +189,11 @@ async function syncContentTypes(
 
 /**
  * Get Zod schema for a content type from its JSON Schema
- * Uses Zod v4's native z.fromJSONSchema() for conversion
+ * Uses formSchemaToZod to properly handle dates, date constraints, and steps metadata
  */
 function getContentTypeZodSchema(contentType: ContentType): z.ZodTypeAny {
 	const jsonSchema = JSON.parse(contentType.jsonSchema);
-	return z.fromJSONSchema(jsonSchema);
+	return formSchemaToZod(jsonSchema);
 }
 
 /**

package/src/plugins/cms/client/components/forms/content-form.tsx

@@ -3,15 +3,13 @@
 import { useState, useMemo, useEffect } from "react";
 import { z } from "zod";
 import { toast } from "sonner";
-import AutoForm, { AutoFormSubmit } from "@workspace/ui/components/auto-form";
+import { SteppedAutoForm } from "@workspace/ui/components/auto-form/stepped-auto-form";
 import type {
 	FieldConfig,
 	AutoFormInputComponentProps,
 } from "@workspace/ui/components/auto-form/types";
-import {
-	buildFieldConfigFromJsonSchema as buildFieldConfigBase,
-	fromJSONSchemaWithDates,
-} from "@workspace/ui/components/auto-form/utils";
+import { buildFieldConfigFromJsonSchema as buildFieldConfigBase } from "@workspace/ui/components/auto-form/utils";
+import { formSchemaToZod } from "@workspace/ui/lib/schema-converter";
 import { Input } from "@workspace/ui/components/input";
 import { Label } from "@workspace/ui/components/label";
 import { Badge } from "@workspace/ui/components/badge";
@@ -168,11 +166,11 @@ export function ContentForm({
 		}
 	}, [contentType.jsonSchema]);
 
-	// Convert JSON Schema to Zod schema using fromJSONSchemaWithDates utility
+	// Convert JSON Schema to Zod schema using formSchemaToZod utility
 	// This properly handles date fields (format: "date-time") and min/max date constraints
 	const zodSchema = useMemo(() => {
 		try {
-			return fromJSONSchemaWithDates(jsonSchema);
+			return formSchemaToZod(jsonSchema);
 		} catch {
 			return z.object({});
 		}
@@ -264,30 +262,30 @@ export function ContentForm({
 			</div>
 
 			{/* Dynamic form from Zod schema */}
-			<AutoForm
+			{/* Uses SteppedAutoForm which automatically handles both single-step and multi-step content types */}
+			<SteppedAutoForm
 				formSchema={zodSchema as z.ZodObject<any, any>}
 				values={formData as any}
 				onValuesChange={handleValuesChange as any}
 				onSubmit={handleSubmit as any}
 				fieldConfig={fieldConfig as any}
+				isSubmitting={isSubmitting}
+				submitButtonText={
+					isSubmitting
+						? localization.CMS_STATUS_SAVING
+						: localization.CMS_BUTTON_SAVE
+				}
 			>
-				<div className="flex items-center gap-2 pt-4">
-					<AutoFormSubmit disabled={isSubmitting}>
-						{isSubmitting
-							? localization.CMS_STATUS_SAVING
-							: localization.CMS_BUTTON_SAVE}
-					</AutoFormSubmit>
-					{onCancel && (
-						<button
-							type="button"
-							onClick={onCancel}
-							className="px-4 py-2 text-sm text-muted-foreground hover:text-foreground"
-						>
-							{localization.CMS_BUTTON_CANCEL}
-						</button>
-					)}
-				</div>
-			</AutoForm>
+				{onCancel && (
+					<button
+						type="button"
+						onClick={onCancel}
+						className="px-4 py-2 text-sm text-muted-foreground hover:text-foreground"
+					>
+						{localization.CMS_BUTTON_CANCEL}
+					</button>
+				)}
+			</SteppedAutoForm>
 		</div>
 	);
 }

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

@@ -6,6 +6,17 @@ export type { CMSLocalization } from "./localization";
 // Re-export AutoFormInputComponentProps for custom field components
 export type { AutoFormInputComponentProps } from "@workspace/ui/components/auto-form/types";
 
+// Re-export schema converter utilities
+export {
+	zodToFormSchema,
+	formSchemaToZod,
+	hasSteps,
+	getSteps,
+	getStepGroupMap,
+	type FormStep,
+	type FormSchemaMetadata,
+} from "@workspace/ui/lib/schema-converter";
+
 // Export CMSFileUpload for consumers to use or extend
 export {
 	CMSFileUpload,

package/src/plugins/form-builder/api/index.ts

@@ -0,0 +1 @@
+export { formBuilderBackendPlugin, type FormBuilderApiRouter } from "./plugin";