@btst/stack 2.11.5 → 2.11.7

package/dist/components/form-builder/index.d.cts

@@ -23,6 +23,14 @@ interface JSONSchema {
     $schema?: string;
     /** Step definitions for multi-step forms (stored in schema meta) */
     steps?: FormStep[];
+    /**
+     * Optional root-level field-name → step-index map. This is the format produced
+     * by `zodToFormSchema(schema, { steps, stepGroupMap })` and consumed by
+     * `SteppedAutoForm`. The visual FormBuilder writes per-property `stepGroup`
+     * instead, but we accept both on read so a Zod-seeded form opens with its
+     * fields correctly assigned to their steps.
+     */
+    stepGroupMap?: Record<string, number>;
     additionalProperties?: boolean;
 }
 /**

package/dist/components/form-builder/index.d.mts

@@ -23,6 +23,14 @@ interface JSONSchema {
     $schema?: string;
     /** Step definitions for multi-step forms (stored in schema meta) */
     steps?: FormStep[];
+    /**
+     * Optional root-level field-name → step-index map. This is the format produced
+     * by `zodToFormSchema(schema, { steps, stepGroupMap })` and consumed by
+     * `SteppedAutoForm`. The visual FormBuilder writes per-property `stepGroup`
+     * instead, but we accept both on read so a Zod-seeded form opens with its
+     * fields correctly assigned to their steps.
+     */
+    stepGroupMap?: Record<string, number>;
     additionalProperties?: boolean;
 }
 /**

package/dist/components/form-builder/index.d.ts

@@ -23,6 +23,14 @@ interface JSONSchema {
     $schema?: string;
     /** Step definitions for multi-step forms (stored in schema meta) */
     steps?: FormStep[];
+    /**
+     * Optional root-level field-name → step-index map. This is the format produced
+     * by `zodToFormSchema(schema, { steps, stepGroupMap })` and consumed by
+     * `SteppedAutoForm`. The visual FormBuilder writes per-property `stepGroup`
+     * instead, but we accept both on read so a Zod-seeded form opens with its
+     * fields correctly assigned to their steps.
+     */
+    stepGroupMap?: Record<string, number>;
     additionalProperties?: boolean;
 }
 /**

package/dist/packages/ui/src/components/form-builder/components/index.cjs

@@ -4,6 +4,7 @@ const LucideIcons = require('lucide-react');
 const z = require('zod');
 const types = require('../types.cjs');
 const validationSchemas = require('../validation-schemas.cjs');
+const helpers = require('../../auto-form/helpers.cjs');
 
 function toNumber(value) {
   if (value == null || value === "") return void 0;
@@ -20,7 +21,7 @@ function getPlaceholder(prop) {
   return prop.inputProps?.placeholder || prop.placeholder;
 }
 function getLabel(prop, key) {
-  return prop.label || prop.title || key;
+  return prop.label || prop.title || helpers.beautifyObjectName(key);
 }
 const textFieldDefinition = types.defineComponent({
   type: "text",

package/dist/packages/ui/src/components/form-builder/components/index.mjs

@@ -2,6 +2,7 @@ import { FolderOpen, List, Mail, Lock, Globe, Phone, Calendar, AlignLeft, Toggle
 import { z } from 'zod';
 import { defineComponent } from '../types.mjs';
 import { baseMetaSchemaWithPlaceholder, stringValidationSchema, DEFAULT_VALUE_SCHEMAS, numberValidationSchema, baseMetaSchema, booleanValidationSchema, enumOptionsSchema, dateValidationSchema, objectValidationSchema, arrayValidationSchema } from '../validation-schemas.mjs';
+import { beautifyObjectName } from '../../auto-form/helpers.mjs';
 
 function toNumber(value) {
   if (value == null || value === "") return void 0;
@@ -18,7 +19,7 @@ function getPlaceholder(prop) {
   return prop.inputProps?.placeholder || prop.placeholder;
 }
 function getLabel(prop, key) {
-  return prop.label || prop.title || key;
+  return prop.label || prop.title || beautifyObjectName(key);
 }
 const textFieldDefinition = defineComponent({
   type: "text",

package/dist/packages/ui/src/components/form-builder/schema-utils.cjs

@@ -1,5 +1,7 @@
 'use strict';
 
+const helpers = require('../auto-form/helpers.cjs');
+
 function fieldsToProperties(fields, components, includeStepGroup = false) {
   const properties = {};
   for (const field of fields) {
@@ -49,7 +51,7 @@ function fieldsToJSONSchema(fields, components, steps) {
     ...hasMultipleSteps ? { steps } : {}
   };
 }
-function propertiesToFields(properties, requiredSet, components) {
+function propertiesToFields(properties, requiredSet, components, stepGroupMap) {
   const fields = [];
   for (const [key, prop] of Object.entries(properties)) {
     const isRequired = requiredSet.has(key);
@@ -60,9 +62,10 @@ function propertiesToFields(properties, requiredSet, components) {
         break;
       }
     }
+    const resolvedStepGroup = prop.stepGroup !== void 0 ? prop.stepGroup : stepGroupMap?.[key];
     if (field) {
-      if (prop.stepGroup !== void 0) {
-        field.stepGroup = prop.stepGroup;
+      if (resolvedStepGroup !== void 0) {
+        field.stepGroup = resolvedStepGroup;
       }
       if (field.type === "object" && prop.properties) {
         const childRequiredSet = new Set(prop.required || []);
@@ -79,13 +82,13 @@ function propertiesToFields(properties, requiredSet, components) {
         id: key,
         type: "text",
         props: {
-          label: prop.title || key,
+          label: prop.label || prop.title || helpers.beautifyObjectName(key),
           description: prop.description,
           placeholder: prop.placeholder,
           required: isRequired
         },
         // Include stepGroup even for fallback fields
-        ...prop.stepGroup !== void 0 ? { stepGroup: prop.stepGroup } : {}
+        ...resolvedStepGroup !== void 0 ? { stepGroup: resolvedStepGroup } : {}
       });
     }
   }
@@ -96,7 +99,12 @@ function jsonSchemaToFieldsAndSteps(schema, components) {
     return { fields: [], steps: [] };
   }
   const requiredSet = new Set(schema.required || []);
-  const fields = propertiesToFields(schema.properties, requiredSet, components);
+  const fields = propertiesToFields(
+    schema.properties,
+    requiredSet,
+    components,
+    schema.stepGroupMap
+  );
   const steps = schema.steps || [];
   return { fields, steps };
 }

package/dist/packages/ui/src/components/form-builder/schema-utils.mjs

@@ -1,3 +1,5 @@
+import { beautifyObjectName } from '../auto-form/helpers.mjs';
+
 function fieldsToProperties(fields, components, includeStepGroup = false) {
   const properties = {};
   for (const field of fields) {
@@ -47,7 +49,7 @@ function fieldsToJSONSchema(fields, components, steps) {
     ...hasMultipleSteps ? { steps } : {}
   };
 }
-function propertiesToFields(properties, requiredSet, components) {
+function propertiesToFields(properties, requiredSet, components, stepGroupMap) {
   const fields = [];
   for (const [key, prop] of Object.entries(properties)) {
     const isRequired = requiredSet.has(key);
@@ -58,9 +60,10 @@ function propertiesToFields(properties, requiredSet, components) {
         break;
       }
     }
+    const resolvedStepGroup = prop.stepGroup !== void 0 ? prop.stepGroup : stepGroupMap?.[key];
     if (field) {
-      if (prop.stepGroup !== void 0) {
-        field.stepGroup = prop.stepGroup;
+      if (resolvedStepGroup !== void 0) {
+        field.stepGroup = resolvedStepGroup;
       }
       if (field.type === "object" && prop.properties) {
         const childRequiredSet = new Set(prop.required || []);
@@ -77,13 +80,13 @@ function propertiesToFields(properties, requiredSet, components) {
         id: key,
         type: "text",
         props: {
-          label: prop.title || key,
+          label: prop.label || prop.title || beautifyObjectName(key),
           description: prop.description,
           placeholder: prop.placeholder,
           required: isRequired
         },
         // Include stepGroup even for fallback fields
-        ...prop.stepGroup !== void 0 ? { stepGroup: prop.stepGroup } : {}
+        ...resolvedStepGroup !== void 0 ? { stepGroup: resolvedStepGroup } : {}
       });
     }
   }
@@ -94,7 +97,12 @@ function jsonSchemaToFieldsAndSteps(schema, components) {
     return { fields: [], steps: [] };
   }
   const requiredSet = new Set(schema.required || []);
-  const fields = propertiesToFields(schema.properties, requiredSet, components);
+  const fields = propertiesToFields(
+    schema.properties,
+    requiredSet,
+    components,
+    schema.stepGroupMap
+  );
   const steps = schema.steps || [];
   return { fields, steps };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btst/stack",
-  "version": "2.11.5",
+  "version": "2.11.7",
   "description": "A composable, plugin-based library for building full-stack applications.",
   "repository": {
     "type": "git",

package/src/plugins/form-builder/__tests__/schema-utils.test.ts

@@ -0,0 +1,449 @@
+/**
+ * Tests for the JSON Schema ↔ FormBuilderField conversion utilities.
+ *
+ * The form-builder ecosystem accepts two flavours of multi-step encoding:
+ *  - **Path A**: per-property `stepGroup` on each field (what the visual
+ *    FormBuilder writes on save — canonical wire format).
+ *  - **Path B**: root-level `stepGroupMap` (what `zodToFormSchema(schema, {
+ *    steps, stepGroupMap })` produces and what `SteppedAutoForm` reads).
+ *
+ * Both must be accepted on read so a Zod-seeded form opens with all fields
+ * correctly assigned to their step tabs in the admin canvas. Without Path B
+ * support, every field in a Zod-seeded multi-step form collapses onto step 0.
+ *
+ * @see packages/ui/src/components/form-builder/schema-utils.ts
+ * @see packages/ui/src/lib/schema-converter.ts
+ */
+
+import { describe, it, expect } from "vitest";
+import {
+	fieldsToJSONSchema,
+	jsonSchemaToFieldsAndSteps,
+} from "@workspace/ui/components/form-builder/schema-utils";
+import { defaultComponents } from "@workspace/ui/components/form-builder";
+import type {
+	JSONSchema,
+	FormStep,
+} from "@workspace/ui/components/form-builder/types";
+
+const STEPS: FormStep[] = [
+	{ id: "goals", title: "Your goals" },
+	{ id: "experience", title: "Experience" },
+	{ id: "constraints", title: "Constraints" },
+];
+
+describe("jsonSchemaToFieldsAndSteps", () => {
+	describe("core usage", () => {
+		it("returns empty result for null/undefined schema", () => {
+			expect(jsonSchemaToFieldsAndSteps(null, defaultComponents)).toEqual({
+				fields: [],
+				steps: [],
+			});
+			expect(jsonSchemaToFieldsAndSteps(undefined, defaultComponents)).toEqual({
+				fields: [],
+				steps: [],
+			});
+		});
+
+		it("returns empty result when schema has no properties", () => {
+			const schema = { type: "object", properties: {} } as JSONSchema;
+			expect(jsonSchemaToFieldsAndSteps(schema, defaultComponents)).toEqual({
+				fields: [],
+				steps: [],
+			});
+		});
+
+		it("parses a flat single-step schema with mixed field types", () => {
+			const schema: JSONSchema = {
+				type: "object",
+				properties: {
+					name: { type: "string", label: "Full Name" },
+					email: { type: "string", format: "email", label: "Email" },
+					age: { type: "number", label: "Age", minimum: 0 },
+				},
+				required: ["name", "email"],
+			};
+
+			const { fields, steps } = jsonSchemaToFieldsAndSteps(
+				schema,
+				defaultComponents,
+			);
+
+			expect(steps).toEqual([]);
+			expect(fields).toHaveLength(3);
+
+			const [name, email, age] = fields;
+			expect(name).toMatchObject({
+				id: "name",
+				type: "text",
+				props: { label: "Full Name", required: true },
+			});
+			expect(email).toMatchObject({
+				id: "email",
+				type: "email",
+				props: { label: "Email", required: true },
+			});
+			expect(age).toMatchObject({
+				id: "age",
+				type: "number",
+				props: { label: "Age", required: false },
+			});
+			expect(name?.stepGroup).toBeUndefined();
+			expect(email?.stepGroup).toBeUndefined();
+			expect(age?.stepGroup).toBeUndefined();
+		});
+
+		it("preserves the steps array on the output", () => {
+			const schema: JSONSchema = {
+				type: "object",
+				properties: {
+					name: { type: "string", label: "Name", stepGroup: 0 },
+				},
+				steps: STEPS,
+			};
+
+			const { steps } = jsonSchemaToFieldsAndSteps(schema, defaultComponents);
+			expect(steps).toEqual(STEPS);
+		});
+	});
+
+	describe("label resolution", () => {
+		// Label resolution must mirror what `AutoForm` shows on the public form,
+		// so a Zod-seeded schema (whose properties only carry `description`,
+		// not `label`/`title`) reads identically in the admin canvas.
+		// See `auto-form/fields/object.tsx` → `beautifyObjectName(name)`.
+
+		it("uses an explicit `label` when present", () => {
+			const schema: JSONSchema = {
+				type: "object",
+				properties: {
+					primaryGoal: {
+						type: "string",
+						label: "What's your main focus?",
+					},
+				},
+			};
+
+			const { fields } = jsonSchemaToFieldsAndSteps(schema, defaultComponents);
+			expect(fields[0]?.props.label).toBe("What's your main focus?");
+		});
+
+		it("falls back to JSON Schema `title` when `label` is absent", () => {
+			const schema: JSONSchema = {
+				type: "object",
+				properties: {
+					primaryGoal: {
+						type: "string",
+						title: "Primary Goal (titled)",
+					},
+				},
+			};
+
+			const { fields } = jsonSchemaToFieldsAndSteps(schema, defaultComponents);
+			expect(fields[0]?.props.label).toBe("Primary Goal (titled)");
+		});
+
+		it("humanises the field key when no `label` or `title` is present", () => {
+			// This is the regression: previously the admin showed the raw key
+			// (`primaryGoal`) when no label/title was set, while the public form
+			// showed `Primary Goal`. Now both paths agree.
+			const schema: JSONSchema = {
+				type: "object",
+				properties: {
+					primaryGoal: { type: "string" },
+					riskTolerance: {
+						type: "string",
+						enum: ["low", "moderate", "high"],
+					},
+					noInjections: { type: "boolean", fieldType: "switch" },
+					email: { type: "string", format: "email" },
+					age: { type: "number" },
+					notes: { type: "string", fieldType: "textarea" },
+				},
+			};
+
+			const { fields } = jsonSchemaToFieldsAndSteps(schema, defaultComponents);
+			const labels = Object.fromEntries(
+				fields.map((f) => [f.id, f.props.label]),
+			);
+
+			expect(labels).toEqual({
+				primaryGoal: "Primary Goal",
+				riskTolerance: "Risk Tolerance",
+				noInjections: "No Injections",
+				email: "Email",
+				age: "Age",
+				notes: "Notes",
+			});
+		});
+
+		it("humanises the field key in the unknown-field-type fallback", () => {
+			// When no component matches, propertiesToFields creates a generic
+			// text field. That branch must humanise the key too.
+			const schema: JSONSchema = {
+				type: "object",
+				properties: {
+					mysteriousField: {
+						// no `type` — falls through to the generic text fallback
+					} as JSONSchema["properties"][string],
+				},
+			};
+
+			const { fields } = jsonSchemaToFieldsAndSteps(schema, defaultComponents);
+			expect(fields[0]?.props.label).toBe("Mysterious Field");
+		});
+	});
+
+	describe("multi-step: Path A — per-property stepGroup", () => {
+		// Canonical format written by the visual FormBuilder when saving.
+		const schema: JSONSchema = {
+			type: "object",
+			properties: {
+				name: { type: "string", label: "Name", stepGroup: 0 },
+				email: {
+					type: "string",
+					format: "email",
+					label: "Email",
+					stepGroup: 0,
+				},
+				experience: {
+					type: "string",
+					enum: ["beginner", "advanced"],
+					label: "Experience",
+					stepGroup: 1,
+				},
+				agree: {
+					type: "boolean",
+					fieldType: "switch",
+					label: "I agree",
+					stepGroup: 2,
+				},
+			},
+			steps: STEPS,
+		};
+
+		it("assigns each field to the step encoded on its property", () => {
+			const { fields } = jsonSchemaToFieldsAndSteps(schema, defaultComponents);
+
+			expect(fields).toHaveLength(4);
+			const byId = new Map(fields.map((f) => [f.id, f]));
+			expect(byId.get("name")?.stepGroup).toBe(0);
+			expect(byId.get("email")?.stepGroup).toBe(0);
+			expect(byId.get("experience")?.stepGroup).toBe(1);
+			expect(byId.get("agree")?.stepGroup).toBe(2);
+		});
+	});
+
+	describe("multi-step: Path B — root-level stepGroupMap (regression)", () => {
+		// What `zodToFormSchema(LooksmaxQuizSchema, { steps, stepGroupMap })` writes.
+		// Before the fix, every field collapsed onto step 0 because the parser
+		// only consulted per-property `stepGroup`.
+		const schema: JSONSchema = {
+			type: "object",
+			properties: {
+				primaryGoal: {
+					type: "string",
+					enum: ["skin", "hair", "jaw", "lean", "all"],
+					label: "Primary goal",
+					fieldType: "radio",
+				},
+				experience: {
+					type: "string",
+					enum: ["none", "some-peptides", "full-cycle-history"],
+					label: "Experience",
+					fieldType: "radio",
+				},
+				riskTolerance: {
+					type: "string",
+					enum: ["low", "moderate", "high"],
+					label: "Risk tolerance",
+					fieldType: "radio",
+				},
+				noInjections: {
+					type: "boolean",
+					fieldType: "switch",
+					label: "No injections",
+				},
+				email: {
+					type: "string",
+					format: "email",
+					label: "Email",
+				},
+			},
+			steps: STEPS,
+			stepGroupMap: {
+				primaryGoal: 0,
+				experience: 1,
+				riskTolerance: 1,
+				noInjections: 2,
+				email: 2,
+			},
+		};
+
+		it("assigns step from root-level stepGroupMap when properties omit stepGroup", () => {
+			const { fields, steps } = jsonSchemaToFieldsAndSteps(
+				schema,
+				defaultComponents,
+			);
+
+			expect(steps).toEqual(STEPS);
+			expect(fields).toHaveLength(5);
+
+			const byId = new Map(fields.map((f) => [f.id, f]));
+			expect(byId.get("primaryGoal")?.stepGroup).toBe(0);
+			expect(byId.get("experience")?.stepGroup).toBe(1);
+			expect(byId.get("riskTolerance")?.stepGroup).toBe(1);
+			expect(byId.get("noInjections")?.stepGroup).toBe(2);
+			expect(byId.get("email")?.stepGroup).toBe(2);
+		});
+
+		it("works for fields that fall back to the generic text component", () => {
+			// Fields with unknown shapes fall through to the fallback `text` field
+			// in propertiesToFields. The fix must apply there too.
+			const schemaWithUnknown: JSONSchema = {
+				type: "object",
+				properties: {
+					mystery: {
+						// no `type` → no component matches → fallback to text
+						label: "Mystery field",
+					} as JSONSchema["properties"][string],
+				},
+				steps: STEPS,
+				stepGroupMap: { mystery: 2 },
+			};
+
+			const { fields } = jsonSchemaToFieldsAndSteps(
+				schemaWithUnknown,
+				defaultComponents,
+			);
+
+			expect(fields).toHaveLength(1);
+			expect(fields[0]?.id).toBe("mystery");
+			expect(fields[0]?.stepGroup).toBe(2);
+		});
+	});
+
+	describe("multi-step: precedence when both encodings are present", () => {
+		it("per-property stepGroup wins over stepGroupMap", () => {
+			const schema: JSONSchema = {
+				type: "object",
+				properties: {
+					primary: {
+						type: "string",
+						label: "Primary",
+						stepGroup: 0, // per-property says step 0
+					},
+					secondary: {
+						type: "string",
+						label: "Secondary",
+						stepGroup: 1, // per-property says step 1
+					},
+					tertiary: {
+						type: "string",
+						label: "Tertiary",
+						// no per-property — should use map
+					},
+				},
+				steps: STEPS,
+				stepGroupMap: {
+					primary: 99, // map disagrees, but per-property wins
+					secondary: 99,
+					tertiary: 2, // map applies
+				},
+			};
+
+			const { fields } = jsonSchemaToFieldsAndSteps(schema, defaultComponents);
+
+			const byId = new Map(fields.map((f) => [f.id, f]));
+			expect(byId.get("primary")?.stepGroup).toBe(0);
+			expect(byId.get("secondary")?.stepGroup).toBe(1);
+			expect(byId.get("tertiary")?.stepGroup).toBe(2);
+		});
+
+		it("missing entries in stepGroupMap leave stepGroup undefined", () => {
+			const schema: JSONSchema = {
+				type: "object",
+				properties: {
+					mapped: { type: "string", label: "Mapped" },
+					unmapped: { type: "string", label: "Unmapped" },
+				},
+				steps: STEPS,
+				stepGroupMap: { mapped: 1 },
+			};
+
+			const { fields } = jsonSchemaToFieldsAndSteps(schema, defaultComponents);
+			const byId = new Map(fields.map((f) => [f.id, f]));
+			expect(byId.get("mapped")?.stepGroup).toBe(1);
+			expect(byId.get("unmapped")?.stepGroup).toBeUndefined();
+		});
+	});
+});
+
+describe("fieldsToJSONSchema → jsonSchemaToFieldsAndSteps round-trip", () => {
+	it("normalises Path B (stepGroupMap) input to Path A (per-property) output", () => {
+		// This is the workflow that breaks the original bug: open a Zod-seeded
+		// form (Path B), save without changes — the FormBuilder writes Path A.
+		const inputSchema: JSONSchema = {
+			type: "object",
+			properties: {
+				goal: { type: "string", label: "Goal" },
+				risk: { type: "string", label: "Risk" },
+			},
+			steps: STEPS.slice(0, 2),
+			stepGroupMap: { goal: 0, risk: 1 },
+		};
+
+		const { fields, steps } = jsonSchemaToFieldsAndSteps(
+			inputSchema,
+			defaultComponents,
+		);
+
+		// Re-serialise with the same steps array
+		const roundTripped = fieldsToJSONSchema(fields, defaultComponents, steps);
+
+		// Output uses Path A (per-property stepGroup) and drops the root-level map
+		expect(roundTripped.properties.goal?.stepGroup).toBe(0);
+		expect(roundTripped.properties.risk?.stepGroup).toBe(1);
+		expect(roundTripped.steps).toEqual(STEPS.slice(0, 2));
+		expect(
+			(roundTripped as JSONSchema & { stepGroupMap?: unknown }).stepGroupMap,
+		).toBeUndefined();
+
+		// And re-parsing the normalised output produces the same field shape
+		const reparsed = jsonSchemaToFieldsAndSteps(
+			roundTripped,
+			defaultComponents,
+		);
+		const byIdOriginal = new Map(fields.map((f) => [f.id, f.stepGroup]));
+		const byIdRoundTrip = new Map(
+			reparsed.fields.map((f) => [f.id, f.stepGroup]),
+		);
+		expect(byIdRoundTrip).toEqual(byIdOriginal);
+	});
+
+	it("preserves Path A through a full round-trip", () => {
+		const inputSchema: JSONSchema = {
+			type: "object",
+			properties: {
+				name: { type: "string", label: "Name", stepGroup: 0 },
+				email: {
+					type: "string",
+					format: "email",
+					label: "Email",
+					stepGroup: 1,
+				},
+			},
+			steps: STEPS.slice(0, 2),
+		};
+
+		const { fields, steps } = jsonSchemaToFieldsAndSteps(
+			inputSchema,
+			defaultComponents,
+		);
+		const roundTripped = fieldsToJSONSchema(fields, defaultComponents, steps);
+
+		expect(roundTripped.properties.name?.stepGroup).toBe(0);
+		expect(roundTripped.properties.email?.stepGroup).toBe(1);
+		expect(roundTripped.steps).toEqual(STEPS.slice(0, 2));
+	});
+});