@btst/stack 1.5.1 → 1.6.0

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,
@@ -16,12 +20,66 @@ import type {
 import { listContentQuerySchema } from "../schemas";
 import { slugify } from "../utils";
 
+/**
+ * Migrate a legacy JSON Schema (version 1) to unified format (version 2)
+ * by merging fieldConfig values into the JSON Schema properties
+ */
+function migrateToUnifiedSchema(
+	jsonSchemaStr: string,
+	fieldConfigStr: string | null | undefined,
+): string {
+	if (!fieldConfigStr) {
+		return jsonSchemaStr;
+	}
+
+	try {
+		const jsonSchema = JSON.parse(jsonSchemaStr);
+		const fieldConfig = JSON.parse(fieldConfigStr);
+
+		if (!jsonSchema.properties || typeof fieldConfig !== "object") {
+			return jsonSchemaStr;
+		}
+
+		// Merge fieldType from fieldConfig into each property
+		for (const [key, config] of Object.entries(fieldConfig)) {
+			if (
+				jsonSchema.properties[key] &&
+				typeof config === "object" &&
+				config !== null &&
+				"fieldType" in config
+			) {
+				jsonSchema.properties[key].fieldType = (
+					config as { fieldType: string }
+				).fieldType;
+			}
+		}
+
+		return JSON.stringify(jsonSchema);
+	} catch {
+		// If parsing fails, return original
+		return jsonSchemaStr;
+	}
+}
+
 /**
  * Serialize a ContentType for API response (convert dates to strings)
+ * Also applies lazy migration for legacy schemas (version 1 → 2)
  */
 function serializeContentType(ct: ContentType): SerializedContentType {
+	// Check if this is a legacy schema that needs migration
+	const needsMigration = !ct.autoFormVersion || ct.autoFormVersion < 2;
+
+	// Apply lazy migration: merge fieldConfig into jsonSchema on read
+	const migratedJsonSchema = needsMigration
+		? migrateToUnifiedSchema(ct.jsonSchema, ct.fieldConfig)
+		: ct.jsonSchema;
+
 	return {
-		...ct,
+		id: ct.id,
+		name: ct.name,
+		slug: ct.slug,
+		description: ct.description,
+		jsonSchema: migratedJsonSchema,
 		createdAt: ct.createdAt.toISOString(),
 		updatedAt: ct.updatedAt.toISOString(),
 	};
@@ -57,6 +115,11 @@ function serializeContentItemWithType(
  * Sync content types from config to database
  * Creates or updates content types based on the developer's Zod schemas
  *
+ * Always writes version 2 format:
+ * - fieldType is embedded in jsonSchema via .meta()
+ * - fieldConfig is set to null (no longer used)
+ * - autoFormVersion is set to 2
+ *
  * Handles race conditions from multiple instances by catching unique constraint
  * errors and verifying the record exists (another instance created it first).
  */
@@ -65,8 +128,9 @@ async function syncContentTypes(
 	config: CMSBackendConfig,
 ): Promise<void> {
 	for (const ct of config.contentTypes) {
-		const jsonSchema = JSON.stringify(z.toJSONSchema(ct.schema));
-		const fieldConfig = ct.fieldConfig ? JSON.stringify(ct.fieldConfig) : null;
+		// 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",
@@ -81,7 +145,8 @@ async function syncContentTypes(
 					name: ct.name,
 					description: ct.description ?? null,
 					jsonSchema,
-					fieldConfig,
+					fieldConfig: null, // No longer used in version 2
+					autoFormVersion: 2,
 					updatedAt: new Date(),
 				},
 			});
@@ -94,7 +159,8 @@ async function syncContentTypes(
 						slug: ct.slug,
 						description: ct.description ?? null,
 						jsonSchema,
-						fieldConfig,
+						fieldConfig: null, // No longer used in version 2
+						autoFormVersion: 2,
 						createdAt: new Date(),
 						updatedAt: new Date(),
 					},
@@ -123,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,13 +3,13 @@
 import { useState, useMemo, useEffect } from "react";
 import { z } from "zod";
 import { toast } from "sonner";
-import AutoForm, {
-	AutoFormSubmit,
-} from "@workspace/ui/components/ui/auto-form";
+import { SteppedAutoForm } from "@workspace/ui/components/auto-form/stepped-auto-form";
 import type {
 	FieldConfig,
 	AutoFormInputComponentProps,
-} from "@workspace/ui/components/ui/auto-form/types";
+} from "@workspace/ui/components/auto-form/types";
+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";
@@ -20,126 +20,6 @@ import { slugify } from "../../../utils";
 import { CMS_LOCALIZATION } from "../../localization";
 import { CMSFileUpload } from "./file-upload";
 
-/**
- * JSON Schema property type definition
- */
-interface JsonSchemaProperty {
-	type?: string | string[];
-	format?: string;
-	enum?: (string | number | boolean)[];
-	minimum?: number;
-	maximum?: number;
-	minLength?: number;
-	maxLength?: number;
-	default?: unknown;
-	description?: string;
-}
-
-interface JsonSchema {
-	type?: string;
-	properties?: Record<string, JsonSchemaProperty>;
-	required?: string[];
-}
-
-/**
- * Convert JSON Schema to Zod schema with proper coercion for AutoForm
- *
- * Uses Zod v4's native z.fromJSONSchema() as a base and applies coercion
- * where needed. AutoForm requires z.coerce.number() and z.coerce.date()
- * for proper form handling because HTML inputs return strings.
- *
- * Note: We build the schema manually to ensure proper coercion support,
- * as z.fromJSONSchema() doesn't add coercion automatically.
- */
-function jsonSchemaToZodWithCoercion(
-	jsonSchema: JsonSchema,
-): z.ZodObject<Record<string, z.ZodTypeAny>> {
-	const shape: Record<string, z.ZodTypeAny> = {};
-	const properties = jsonSchema.properties || {};
-	const required = jsonSchema.required || [];
-
-	for (const [key, prop] of Object.entries(properties)) {
-		let fieldSchema: z.ZodTypeAny;
-
-		// Determine the type (handle arrays like ["string", "null"] for nullable)
-		const typeValue = Array.isArray(prop.type) ? prop.type[0] : prop.type;
-
-		// Handle enum first - works for string enums
-		if (prop.enum && Array.isArray(prop.enum) && prop.enum.length > 0) {
-			// Filter to only string values for z.enum
-			const stringValues = prop.enum.filter(
-				(v): v is string => typeof v === "string",
-			);
-			if (stringValues.length > 0) {
-				fieldSchema = z.enum(stringValues as [string, ...string[]]);
-			} else {
-				// Fallback for non-string enums
-				fieldSchema = z.string();
-			}
-		} else {
-			switch (typeValue) {
-				case "number":
-				case "integer": {
-					// Use z.coerce.number() for proper form handling (HTML inputs return strings)
-					let numSchema = z.coerce.number();
-					if (prop.minimum !== undefined) {
-						numSchema = numSchema.min(prop.minimum);
-					}
-					if (prop.maximum !== undefined) {
-						numSchema = numSchema.max(prop.maximum);
-					}
-					fieldSchema = numSchema;
-					break;
-				}
-				case "boolean": {
-					fieldSchema = z.boolean();
-					if (prop.default !== undefined) {
-						fieldSchema = (fieldSchema as z.ZodBoolean).default(
-							prop.default as boolean,
-						);
-					}
-					break;
-				}
-				case "string": {
-					// Check for date format
-					if (prop.format === "date" || prop.format === "date-time") {
-						fieldSchema = z.coerce.date();
-					} else {
-						let strSchema = z.string();
-						if (prop.minLength !== undefined) {
-							strSchema = strSchema.min(prop.minLength);
-						}
-						if (prop.maxLength !== undefined) {
-							strSchema = strSchema.max(prop.maxLength);
-						}
-						fieldSchema = strSchema;
-					}
-					break;
-				}
-				default: {
-					// Fallback to string for unknown types
-					fieldSchema = z.string();
-				}
-			}
-		}
-
-		// Apply default if present and not already applied (skip for booleans which handle it above)
-		// Use typeValue to correctly handle nullable types where prop.type is an array like ["boolean", "null"]
-		if (prop.default !== undefined && typeValue !== "boolean") {
-			fieldSchema = fieldSchema.default(prop.default);
-		}
-
-		// Make optional if not in required array
-		if (!required.includes(key)) {
-			fieldSchema = fieldSchema.optional();
-		}
-
-		shape[key] = fieldSchema;
-	}
-
-	return z.object(shape);
-}
-
 interface ContentFormProps {
 	contentType: SerializedContentType;
 	initialData?: Record<string, unknown>;
@@ -153,112 +33,63 @@ interface ContentFormProps {
 }
 
 /**
- * Built-in AutoForm field types
- */
-const BUILTIN_FIELD_TYPES = [
-	"checkbox",
-	"date",
-	"select",
-	"radio",
-	"switch",
-	"textarea",
-	"number",
-	"file",
-	"fallback",
-] as const;
-
-/**
- * Extract field configuration from JSON Schema properties
- * Maps description and placeholder to AutoForm's fieldConfig format
+ * Build field configuration for AutoForm with CMS-specific file upload handling.
+ *
+ * Uses the shared buildFieldConfigFromJsonSchema from auto-form/utils as a base,
+ * then adds special handling for "file" fieldType to inject CMSFileUpload component
+ * ONLY if no custom component is provided via fieldComponents.
  *
- * @param jsonSchema - The JSON Schema from the content type
- * @param storedFieldConfig - The stored field config from the content type
- * @param uploadImage - The uploadImage function from overrides (for default file component)
+ * @param jsonSchema - The JSON Schema from the content type (with fieldType embedded in properties)
+ * @param uploadImage - The uploadImage function from overrides (for file fields)
  * @param fieldComponents - Custom field components from overrides
  */
 function buildFieldConfigFromJsonSchema(
 	jsonSchema: Record<string, unknown>,
-	storedFieldConfig?: Record<string, { fieldType?: string }>,
 	uploadImage?: (file: File) => Promise<string>,
 	fieldComponents?: Record<
 		string,
 		React.ComponentType<AutoFormInputComponentProps>
 	>,
 ): FieldConfig<Record<string, unknown>> {
-	const fieldConfig: FieldConfig<Record<string, unknown>> = {};
+	// Get base config from shared utility (handles fieldType from JSON Schema)
+	const baseConfig = buildFieldConfigBase(jsonSchema, fieldComponents);
+
+	// Apply CMS-specific handling for "file" fieldType ONLY if no custom component exists
+	// Custom fieldComponents take priority - don't override if user provided one
 	const properties = jsonSchema.properties as Record<
 		string,
-		{ description?: string; placeholder?: string }
+		{ fieldType?: string }
 	>;
 
-	if (!properties) return fieldConfig;
-
-	for (const [key, value] of Object.entries(properties)) {
-		const config: Record<string, unknown> = {};
-
-		if (value.description) {
-			config.description = value.description;
-		}
-
-		if (value.placeholder) {
-			config.inputProps = {
-				placeholder: value.placeholder,
-			};
-		}
-
-		// Apply stored fieldConfig overrides (e.g., fieldType: "textarea", "file", or custom types)
-		if (storedFieldConfig?.[key]) {
-			const storedConfig = storedFieldConfig[key];
-			const fieldType = storedConfig.fieldType;
+	if (!properties) return baseConfig;
 
-			if (fieldType) {
-				// 1. Check if there's a custom component in fieldComponents
-				if (fieldComponents?.[fieldType]) {
-					const CustomComponent = fieldComponents[fieldType];
-					config.fieldType = (props: AutoFormInputComponentProps) => (
-						<CustomComponent {...props} />
-					);
-				}
-				// 2. Special handling for built-in "file" type - use CMSFileUpload with uploadImage
-				else if (fieldType === "file") {
-					if (!uploadImage) {
-						// Show a clear error message if uploadImage is not provided
-						config.fieldType = () => (
-							<div className="rounded-md border border-destructive bg-destructive/10 p-3 text-sm text-destructive">
-								File upload requires an <code>uploadImage</code> function in CMS
-								overrides.
-							</div>
-						);
-					} else {
-						config.fieldType = (props: AutoFormInputComponentProps) => (
-							<CMSFileUpload {...props} uploadImage={uploadImage} />
-						);
-					}
-				}
-				// 3. For other built-in types, pass through to auto-form
-				else if (
-					BUILTIN_FIELD_TYPES.includes(
-						fieldType as (typeof BUILTIN_FIELD_TYPES)[number],
-					)
-				) {
-					config.fieldType = fieldType;
-				}
-				// 4. Unknown custom type without a component - log warning and skip
-				else {
-					console.warn(
-						`CMS: Unknown fieldType "${fieldType}" for field "${key}". ` +
-							`Provide a component via fieldComponents override or use a built-in type.`,
-					);
-				}
+	for (const [key, prop] of Object.entries(properties)) {
+		// Only handle "file" fieldType when there's NO custom component for "file"
+		if (prop.fieldType === "file" && !fieldComponents?.["file"]) {
+			// Use CMSFileUpload as the default file component
+			if (!uploadImage) {
+				// Show a clear error message if uploadImage is not provided
+				baseConfig[key] = {
+					...baseConfig[key],
+					fieldType: () => (
+						<div className="rounded-md border border-destructive bg-destructive/10 p-3 text-sm text-destructive">
+							File upload requires an <code>uploadImage</code> function in CMS
+							overrides.
+						</div>
+					),
+				};
+			} else {
+				baseConfig[key] = {
+					...baseConfig[key],
+					fieldType: (props: AutoFormInputComponentProps) => (
+						<CMSFileUpload {...props} uploadImage={uploadImage} />
+					),
+				};
 			}
 		}
-
-		if (Object.keys(config).length > 0) {
-			fieldConfig[key] = config;
-		}
 	}
 
-	return fieldConfig;
+	return baseConfig;
 }
 
 /**
@@ -326,7 +157,7 @@ export function ContentForm({
 		}
 	}, [initialSlug, isEditing]);
 
-	// Parse JSON Schema
+	// Parse JSON Schema (now includes fieldType embedded in properties)
 	const jsonSchema = useMemo(() => {
 		try {
 			return JSON.parse(contentType.jsonSchema) as Record<string, unknown>;
@@ -335,38 +166,21 @@ export function ContentForm({
 		}
 	}, [contentType.jsonSchema]);
 
-	// Parse stored field config
-	const storedFieldConfig = useMemo(() => {
-		if (!contentType.fieldConfig) return undefined;
-		try {
-			return JSON.parse(contentType.fieldConfig) as Record<
-				string,
-				{ fieldType?: string }
-			>;
-		} catch {
-			return undefined;
-		}
-	}, [contentType.fieldConfig]);
-
-	// Convert to Zod schema with coercion for proper AutoForm handling
+	// 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 jsonSchemaToZodWithCoercion(jsonSchema as JsonSchema);
+			return formSchemaToZod(jsonSchema);
 		} catch {
 			return z.object({});
 		}
 	}, [jsonSchema]);
 
-	// Build field config for AutoForm
+	// Build field config for AutoForm (fieldType is now embedded in jsonSchema)
 	const fieldConfig = useMemo(
 		() =>
-			buildFieldConfigFromJsonSchema(
-				jsonSchema,
-				storedFieldConfig,
-				uploadImage,
-				fieldComponents,
-			),
-		[jsonSchema, storedFieldConfig, uploadImage, fieldComponents],
+			buildFieldConfigFromJsonSchema(jsonSchema, uploadImage, fieldComponents),
+		[jsonSchema, uploadImage, fieldComponents],
 	);
 
 	// Find the field to use for slug auto-generation
@@ -448,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/components/forms/file-upload.tsx

@@ -2,7 +2,7 @@
 
 import { useState, useCallback, useEffect, type ChangeEvent } from "react";
 import { toast } from "sonner";
-import type { AutoFormInputComponentProps } from "@workspace/ui/components/ui/auto-form/types";
+import type { AutoFormInputComponentProps } from "@workspace/ui/components/auto-form/types";
 import { Input } from "@workspace/ui/components/input";
 import { Button } from "@workspace/ui/components/button";
 import {
@@ -11,8 +11,8 @@ import {
 	FormMessage,
 } from "@workspace/ui/components/form";
 import { Trash2, Loader2 } from "lucide-react";
-import AutoFormLabel from "@workspace/ui/components/ui/auto-form/common/label";
-import AutoFormTooltip from "@workspace/ui/components/ui/auto-form/common/tooltip";
+import AutoFormLabel from "@workspace/ui/components/auto-form/common/label";
+import AutoFormTooltip from "@workspace/ui/components/auto-form/common/tooltip";
 
 /**
  * Props for the CMSFileUpload component

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

@@ -4,7 +4,18 @@ export type { CMSPluginOverrides, RouteContext } from "./overrides";
 export type { CMSLocalization } from "./localization";
 
 // Re-export AutoFormInputComponentProps for custom field components
-export type { AutoFormInputComponentProps } from "@workspace/ui/components/ui/auto-form/types";
+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 {

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

@@ -1,6 +1,6 @@
 import type { ComponentType } from "react";
 import type { CMSLocalization } from "./localization";
-import type { AutoFormInputComponentProps } from "@workspace/ui/components/ui/auto-form/types";
+import type { AutoFormInputComponentProps } from "@workspace/ui/components/auto-form/types";
 
 /**
  * Context passed to lifecycle hooks

package/src/plugins/cms/db.ts

@@ -29,6 +29,10 @@ export const cmsSchema = createDbPlugin("cms", {
 				type: "string",
 				required: false,
 			},
+			autoFormVersion: {
+				type: "number",
+				required: false,
+			},
 			createdAt: {
 				type: "date",
 				defaultValue: () => new Date(),

package/src/plugins/cms/schemas.ts

@@ -31,6 +31,7 @@ export const updateContentSchema = z.object({
 
 /**
  * Schema for content type response
+ * Note: fieldConfig is no longer included - it's merged into jsonSchema during read
  */
 export const contentTypeResponseSchema = z.object({
 	id: z.string(),
@@ -38,7 +39,6 @@ export const contentTypeResponseSchema = z.object({
 	slug: z.string(),
 	description: z.string().nullable().optional(),
 	jsonSchema: z.string(),
-	fieldConfig: z.string().nullable().optional(),
 	createdAt: z.string(),
 	updatedAt: z.string(),
 });

package/src/plugins/cms/types.ts

@@ -1,8 +1,16 @@
 import type { z } from "zod";
-import type { AutoFormFieldType } from "@workspace/ui/components/ui/auto-form/types";
 
 /**
- * Configuration for a content type defined by the developer
+ * Configuration for a content type defined by the developer.
+ *
+ * Field types are now specified directly in the Zod schema via .meta():
+ * @example
+ * ```typescript
+ * const ProductSchema = z.object({
+ *   description: z.string().meta({ fieldType: "textarea" }),
+ *   image: z.string().optional().meta({ fieldType: "file" }),
+ * });
+ * ```
  */
 export interface ContentTypeConfig {
 	/** Display name for the content type (e.g., "Product", "Testimonial") */
@@ -11,21 +19,8 @@ export interface ContentTypeConfig {
 	slug: string;
 	/** Optional description shown in the admin UI */
 	description?: string;
-	/** Zod schema defining the content type's fields */
+	/** Zod schema defining the content type's fields. Use .meta({ fieldType: "..." }) for field type overrides. */
 	schema: z.ZodObject<z.ZodRawShape>;
-	/**
-	 * Optional field configuration for AutoForm customization.
-	 *
-	 * fieldType can be:
-	 * - A built-in AutoForm type: "checkbox", "date", "select", "radio", "switch", "textarea", "number", "file", "fallback"
-	 * - A custom type name that maps to a component provided via `fieldComponents` in overrides
-	 */
-	fieldConfig?: Record<
-		string,
-		{
-			fieldType?: AutoFormFieldType | (string & {});
-		}
-	>;
 }
 
 /**
@@ -41,8 +36,10 @@ export type ContentType = {
 	description?: string;
 	/** JSON Schema representation of the Zod schema (stringified) */
 	jsonSchema: string;
-	/** Optional field configuration JSON (stringified) */
+	/** @deprecated Legacy field config - now embedded in jsonSchema. Kept for backwards compat. */
 	fieldConfig?: string;
+	/** AutoForm schema version. 1 = legacy (separate fieldConfig), 2 = unified (fieldType in jsonSchema) */
+	autoFormVersion?: number;
 	createdAt: Date;
 	updatedAt: Date;
 };

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

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