@btst/stack 1.5.1 → 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/dist/shared/{stack.DwnJA87a.d.ts → stack.L-UFwz2G.d.cts}

@@ -1,8 +1,16 @@
 import { z } from 'zod';
-import { A as AutoFormFieldType } from './stack.NZJogTUn.js';
 
 /**
- * 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" }),
+ * });
+ * ```
  */
 interface ContentTypeConfig {
     /** Display name for the content type (e.g., "Product", "Testimonial") */
@@ -11,18 +19,8 @@ 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 & {});
-    }>;
 }
 /**
  * Content type stored in the database
@@ -37,8 +35,10 @@ 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/dist/shared/{stack.BwkyFwF8.d.cts → stack.L-UFwz2G.d.mts}

@@ -1,8 +1,16 @@
 import { z } from 'zod';
-import { A as AutoFormFieldType } from './stack.NZJogTUn.cjs';
 
 /**
- * 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" }),
+ * });
+ * ```
  */
 interface ContentTypeConfig {
     /** Display name for the content type (e.g., "Product", "Testimonial") */
@@ -11,18 +19,8 @@ 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 & {});
-    }>;
 }
 /**
  * Content type stored in the database
@@ -37,8 +35,10 @@ 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/dist/shared/{stack.DBqxCs0V.d.mts → stack.L-UFwz2G.d.ts}

@@ -1,8 +1,16 @@
 import { z } from 'zod';
-import { A as AutoFormFieldType } from './stack.NZJogTUn.mjs';
 
 /**
- * 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" }),
+ * });
+ * ```
  */
 interface ContentTypeConfig {
     /** Display name for the content type (e.g., "Product", "Testimonial") */
@@ -11,18 +19,8 @@ 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 & {});
-    }>;
 }
 /**
  * Content type stored in the database
@@ -37,8 +35,10 @@ 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btst/stack",
-  "version": "1.5.1",
+  "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/__tests__/schema-roundtrip.test.ts

@@ -338,6 +338,201 @@ describe("Zod to JSON Schema roundtrip", () => {
 		});
 	});
 
+	describe("Unified schema format with fieldType in .meta()", () => {
+		it("preserves fieldType in JSON Schema properties", () => {
+			const schema = z.object({
+				description: z.string().meta({
+					description: "Full description",
+					fieldType: "textarea",
+				}),
+				image: z.string().optional().meta({
+					description: "Image URL",
+					fieldType: "file",
+				}),
+			});
+
+			const jsonSchema = z.toJSONSchema(schema) as {
+				properties?: Record<
+					string,
+					{ description?: string; fieldType?: string }
+				>;
+			};
+
+			// fieldType should be preserved in JSON Schema properties
+			expect(jsonSchema.properties?.description?.fieldType).toBe("textarea");
+			expect(jsonSchema.properties?.image?.fieldType).toBe("file");
+		});
+
+		it("preserves placeholder in JSON Schema properties", () => {
+			const schema = z.object({
+				name: z.string().meta({
+					placeholder: "Enter product name...",
+				}),
+			});
+
+			const jsonSchema = z.toJSONSchema(schema) as {
+				properties?: Record<string, { placeholder?: string }>;
+			};
+
+			expect(jsonSchema.properties?.name?.placeholder).toBe(
+				"Enter product name...",
+			);
+		});
+
+		it("simulates unified schema storage and retrieval", () => {
+			// This test simulates the new CMS flow with unified schema:
+			// 1. Developer defines schema with fieldType in .meta()
+			// 2. Backend converts to JSON Schema and stores (fieldType embedded)
+			// 3. Client reads JSON Schema and extracts fieldType for AutoForm
+
+			// Step 1: Developer defines schema with fieldType in .meta()
+			const ProductSchema = z.object({
+				name: z.string().min(1).meta({
+					description: "Product name",
+					placeholder: "Enter name...",
+				}),
+				description: z.string().meta({
+					description: "Full description",
+					fieldType: "textarea",
+				}),
+				image: z.string().optional().meta({
+					description: "Product image",
+					fieldType: "file",
+				}),
+				price: z.number().min(0).meta({
+					placeholder: "0.00",
+				}),
+			});
+
+			// Step 2: Convert to JSON Schema (stored in DB as version 2)
+			const jsonSchema = z.toJSONSchema(ProductSchema);
+			const dbStoredString = JSON.stringify(jsonSchema);
+
+			// Step 3: Client fetches and extracts fieldTypes
+			const fetchedSchema = JSON.parse(dbStoredString) as {
+				properties?: Record<
+					string,
+					{ description?: string; placeholder?: string; fieldType?: string }
+				>;
+			};
+
+			// Verify fieldTypes are preserved
+			expect(fetchedSchema.properties?.description?.fieldType).toBe("textarea");
+			expect(fetchedSchema.properties?.image?.fieldType).toBe("file");
+
+			// Verify other meta properties are preserved
+			expect(fetchedSchema.properties?.name?.description).toBe("Product name");
+			expect(fetchedSchema.properties?.name?.placeholder).toBe("Enter name...");
+			expect(fetchedSchema.properties?.price?.placeholder).toBe("0.00");
+		});
+	});
+
+	describe("Legacy schema migration", () => {
+		/**
+		 * Simulates the migrateToUnifiedSchema function from api/plugin.ts
+		 */
+		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 {
+				return jsonSchemaStr;
+			}
+		}
+
+		it("merges legacy fieldConfig into JSON Schema", () => {
+			// Legacy format: separate jsonSchema and fieldConfig
+			const legacyJsonSchema = JSON.stringify({
+				type: "object",
+				properties: {
+					name: { type: "string", description: "Product name" },
+					description: { type: "string" },
+					image: { type: "string" },
+				},
+				required: ["name", "description"],
+			});
+
+			const legacyFieldConfig = JSON.stringify({
+				description: { fieldType: "textarea" },
+				image: { fieldType: "file" },
+			});
+
+			// Migrate
+			const migratedStr = migrateToUnifiedSchema(
+				legacyJsonSchema,
+				legacyFieldConfig,
+			);
+			const migrated = JSON.parse(migratedStr);
+
+			// Verify fieldTypes are now embedded
+			expect(migrated.properties.description.fieldType).toBe("textarea");
+			expect(migrated.properties.image.fieldType).toBe("file");
+
+			// Verify other properties are preserved
+			expect(migrated.properties.name.description).toBe("Product name");
+			expect(migrated.required).toEqual(["name", "description"]);
+		});
+
+		it("handles null fieldConfig", () => {
+			const jsonSchema = JSON.stringify({
+				type: "object",
+				properties: {
+					name: { type: "string" },
+				},
+			});
+
+			const result = migrateToUnifiedSchema(jsonSchema, null);
+			expect(result).toBe(jsonSchema);
+		});
+
+		it("handles undefined fieldConfig", () => {
+			const jsonSchema = JSON.stringify({
+				type: "object",
+				properties: {
+					name: { type: "string" },
+				},
+			});
+
+			const result = migrateToUnifiedSchema(jsonSchema, undefined);
+			expect(result).toBe(jsonSchema);
+		});
+
+		it("handles invalid JSON gracefully", () => {
+			const jsonSchema = "invalid json";
+			const fieldConfig = "also invalid";
+
+			const result = migrateToUnifiedSchema(jsonSchema, fieldConfig);
+			expect(result).toBe(jsonSchema); // Returns original on error
+		});
+	});
+
 	describe("AutoForm schema generation and data shape", () => {
 		/**
 		 * Helper function to convert JSON Schema to Zod with coercion for AutoForm