@classytic/formkit 1.3.1 → 1.5.0

package/dist/server.mjs

@@ -85,6 +85,14 @@ function toRules(condition) {
 		logic: "and"
 	};
 }
+function resolveRuleObject(rule, defaultMessage) {
+	if (rule !== null && typeof rule === "object" && "value" in rule && "message" in rule) return rule;
+	const v = rule;
+	return {
+		value: v,
+		message: defaultMessage(v)
+	};
+}
 /**
 * Evaluates a conditional rule, array of rules, or a ConditionConfig against form values.
 * Supports AND (default) and OR logic via ConditionConfig.
@@ -135,6 +143,7 @@ function defineSection(section) {
 /**
 * Extracts default values from a form schema.
 * Walks all sections and fields, respecting nameSpace prefixes and group nesting.
+* Array fields default to `[]` when no explicit `defaultValue` is provided.
 *
 * @example
 * ```ts
@@ -145,22 +154,228 @@ function defineSection(section) {
 function extractDefaultValues(schema) {
 	const defaults = {};
 	for (const section of schema.sections) {
-		const prefix = section.nameSpace ? `${section.nameSpace}.` : "";
 		if (!section.fields) continue;
-		for (const field of section.fields) {
-			if (field.defaultValue !== void 0) defaults[`${prefix}${field.name}`] = field.defaultValue;
-			if (field.itemFields && field.type !== "array") {
-				for (const sub of field.itemFields) if (sub.defaultValue !== void 0) defaults[`${prefix}${field.name}.${sub.name}`] = sub.defaultValue;
-			}
-		}
+		collectExplicitDefaults(section.fields, section.nameSpace ?? "", defaults);
 	}
 	return defaults;
 }
 /**
+* Recursively assign a field list's EXPLICIT defaults (sparse — only fields
+* that declare a `defaultValue`, plus `array` fields seeded to `[]`) into
+* `target` at the given dot-path prefix. Recurses into nested `group` children
+* so deeply-nested defaults aren't dropped; `array` children are left dynamic.
+*/
+function collectExplicitDefaults(fields, prefix, target) {
+	for (const field of fields) {
+		const name = field.name;
+		const key = prefix ? `${prefix}.${name}` : name;
+		if (field.defaultValue !== void 0) assignPath(target, key, field.defaultValue);
+		else if (field.type === "array") assignPath(target, key, []);
+		else if (field.itemFields && field.itemFields.length > 0) collectExplicitDefaults(field.itemFields, key, target);
+	}
+}
+const VALID_OPERATORS = new Set([
+	"===",
+	"!==",
+	"in",
+	"not-in",
+	"truthy",
+	"falsy"
+]);
+const CONTAINER_TYPES = new Set(["group", "array"]);
+/**
+* Structurally validate a form schema and return a list of issues (empty ⇒ OK).
+* Server-safe (no hooks/DOM), so you can run it when a schema is loaded from a
+* DB, in a test, or in a dev boot check. It validates SHAPE, not your component
+* registry — an unknown field `type` is a registry concern, not a schema error.
+*
+* Checks: missing `name`/`type`, duplicate names (namespace-aware), `itemFields`
+* on a non-container type, containers with no `itemFields`, and unknown DSL
+* condition operators.
+*/
+function validateSchema(schema) {
+	const issues = [];
+	const seen = /* @__PURE__ */ new Map();
+	const checkCondition = (condition, path) => {
+		if (!condition || typeof condition === "function") return;
+		const asObj = condition;
+		const rules = Array.isArray(condition) ? condition : Array.isArray(asObj.rules) ? asObj.rules : [condition];
+		for (const rule of rules) {
+			const op = rule?.operator;
+			if (op && !VALID_OPERATORS.has(op)) issues.push({
+				path,
+				code: "unknown-operator",
+				severity: "error",
+				message: `Unknown condition operator "${op}". Valid: ${[...VALID_OPERATORS].join(", ")}.`
+			});
+		}
+	};
+	const walkFields = (fields, prefix, locPath, dedup) => {
+		fields.forEach((field, i) => {
+			const loc = `${locPath}.fields[${i}]`;
+			const name = field.name;
+			if (!name) issues.push({
+				path: loc,
+				code: "missing-name",
+				severity: "error",
+				message: "Field is missing a `name`."
+			});
+			if (!field.type) issues.push({
+				path: loc,
+				code: "missing-type",
+				severity: "error",
+				message: `Field "${name ?? "?"}" is missing a \`type\`.`
+			});
+			if (name && dedup) {
+				const full = prefix ? `${prefix}.${name}` : name;
+				const prior = seen.get(full);
+				if (prior) issues.push({
+					path: loc,
+					code: "duplicate-name",
+					severity: "error",
+					message: `Duplicate field name "${full}" (also at ${prior}).`
+				});
+				else seen.set(full, loc);
+			}
+			const hasItems = !!field.itemFields && field.itemFields.length > 0;
+			const isContainer = CONTAINER_TYPES.has(field.type);
+			if (hasItems && !isContainer) issues.push({
+				path: loc,
+				code: "itemfields-on-noncontainer",
+				severity: "error",
+				message: `Field "${name}" has \`itemFields\` but type "${field.type}" is not a container (group/array).`
+			});
+			if (isContainer && !hasItems) issues.push({
+				path: loc,
+				code: "empty-container",
+				severity: "warning",
+				message: `Container field "${name}" (${field.type}) has no \`itemFields\`.`
+			});
+			checkCondition(field.condition, loc);
+			if (hasItems) {
+				const childDedup = field.type !== "array" && dedup;
+				const childPrefix = field.type === "array" ? "" : name ? prefix ? `${prefix}.${name}` : name : prefix;
+				walkFields(field.itemFields, childPrefix, loc, childDedup);
+			}
+		});
+	};
+	schema.sections.forEach((section, i) => {
+		const loc = `sections[${i}]`;
+		checkCondition(section.condition, loc);
+		if (section.fields) walkFields(section.fields, section.nameSpace ?? "", loc, true);
+	});
+	return issues;
+}
+/**
+* Build a default-value object for a flat list of fields — used to seed a new
+* array item (or a group) from its `itemFields`.
+*
+* Recurses into nested `group` children (→ nested object) and seeds nested
+* `array` children as `[]`, so appending an item never leaves a deep sub-field
+* `undefined`. That matters because a missing deep field can trip a resolver
+* (zod et al.) into a spurious "required" error the moment the row is added.
+* Leaf fields without an explicit `defaultValue` seed to `""` (a controlled
+* empty value RHF is happy with).
+*/
+function buildFieldDefaults(fields) {
+	const item = {};
+	if (!fields) return item;
+	for (const f of fields) {
+		const name = f.name;
+		if (f.defaultValue !== void 0) item[name] = f.defaultValue;
+		else if (f.type === "array") item[name] = [];
+		else if (f.itemFields && f.itemFields.length > 0) item[name] = buildFieldDefaults(f.itemFields);
+		else item[name] = emptyForType(f.type);
+	}
+	return item;
+}
+/**
+* Type-appropriate "empty" seed for a leaf field that declares no
+* `defaultValue`. A blanket `""` is wrong for non-text fields — a checkbox
+* seeded to `""` is neither on nor off, and a numeric field coerces `""` to
+* `NaN`. Text-like fields fall through to `""`.
+*/
+function emptyForType(type) {
+	switch (type) {
+		case "checkbox":
+		case "switch":
+		case "boolean": return false;
+		case "number":
+		case "money": return;
+		case "multiselect":
+		case "tags": return [];
+		default: return "";
+	}
+}
+/**
+* Assign a possibly dot-notated key into a NESTED object shape:
+* `assignPath(obj, "address.city", "NYC")` → `obj.address.city = "NYC"`.
+*
+* Nested (not flat `{"address.city": ...}`) is required for react-hook-form:
+* its `get(defaultValues, "address.city")` resolves through the object graph,
+* so a flat dotted key would never be found and the field's default would
+* silently not apply. Top-level keys (no dot) are assigned directly.
+*/
+function assignPath(target, path, value) {
+	if (!path.includes(".")) {
+		target[path] = value;
+		return;
+	}
+	const parts = path.split(".");
+	const last = parts.length - 1;
+	let node = target;
+	for (let i = 0; i < last; i++) {
+		const key = parts[i];
+		const next = node[key];
+		if (typeof next !== "object" || next === null || Array.isArray(next)) node[key] = {};
+		node = node[key];
+	}
+	node[parts[last]] = value;
+}
+/**
+* True for objects that are safe to spread-merge: plain `{}` records (or
+* `Object.create(null)`). A Date / File / class instance is `typeof "object"`
+* but must be REPLACED wholesale, never spread-merged — `{ ...new Date() }` is
+* `{}`, which would silently destroy the value.
+*/
+function isPlainObject(v) {
+	if (typeof v !== "object" || v === null) return false;
+	const proto = Object.getPrototypeOf(v);
+	return proto === Object.prototype || proto === null;
+}
+/**
+* Deep-merge `override` onto `base` with default-values semantics: nested
+* plain objects merge recursively; arrays, primitives, and class instances
+* (Date, File, …) from `override` replace wholesale.
+*
+* This is the merge `useFormKit` applies between schema-extracted defaults and
+* caller-provided `defaultValues`. Exported so wrappers that re-seed a form at
+* runtime (e.g. an edit sheet swapping entities) can reproduce the exact same
+* merge for `form.reset(...)`:
+*
+* @example
+* ```ts
+* const merged = mergeDefaultValues(extractDefaultValues(schema), entity);
+* form.reset(merged);
+* ```
+*/
+function mergeDefaultValues(base, override) {
+	const out = { ...base };
+	for (const key of Object.keys(override)) {
+		const b = out[key];
+		const o = override[key];
+		out[key] = isPlainObject(b) && isPlainObject(o) ? mergeDefaultValues(b, o) : o;
+	}
+	return out;
+}
+/**
 * Generates react-hook-form `RegisterOptions`-compatible validation rules
 * from a field's schema props. Maps `required`, `min`, `max`, `minLength`,
 * `maxLength`, `pattern`, and `validate` to RHF rules.
 *
+* Supports both shorthand scalars and `{ value, message }` objects for all
+* numeric/length rules, and `{ regex, message }` for pattern.
+*
 * @example
 * ```tsx
 * import { buildValidationRules } from '@classytic/formkit';
@@ -173,229 +388,506 @@ function extractDefaultValues(schema) {
 */
 function buildValidationRules(field) {
 	const rules = {};
-	if (field.required) rules.required = `${field.label || field.name} is required`;
-	if (field.minLength !== void 0) rules.minLength = {
-		value: field.minLength,
-		message: `At least ${field.minLength} characters`
-	};
-	if (field.maxLength !== void 0) rules.maxLength = {
-		value: field.maxLength,
-		message: `At most ${field.maxLength} characters`
-	};
-	if (field.min !== void 0) rules.min = {
-		value: field.min,
-		message: `Must be at least ${field.min}`
+	if (field.required) rules.required = {
+		value: true,
+		message: `${field.label || field.name} is required`
 	};
-	if (field.max !== void 0) rules.max = {
-		value: field.max,
-		message: `Must be at most ${field.max}`
-	};
-	if (field.pattern) try {
-		rules.pattern = {
-			value: new RegExp(field.pattern),
-			message: "Invalid format"
+	if (field.minLength !== void 0) {
+		const { value, message } = resolveRuleObject(field.minLength, (v) => `At least ${v} characters`);
+		rules.minLength = {
+			value,
+			message
+		};
+	}
+	if (field.maxLength !== void 0) {
+		const { value, message } = resolveRuleObject(field.maxLength, (v) => `At most ${v} characters`);
+		rules.maxLength = {
+			value,
+			message
+		};
+	}
+	if (field.min !== void 0) {
+		const { value, message } = resolveRuleObject(field.min, (v) => `Must be at least ${v}`);
+		rules.min = {
+			value,
+			message
+		};
+	}
+	if (field.max !== void 0) {
+		const { value, message } = resolveRuleObject(field.max, (v) => `Must be at most ${v}`);
+		rules.max = {
+			value,
+			message
 		};
-	} catch {
-		console.warn(`[FormKit] Invalid regex pattern "${field.pattern}" in field "${field.name}", skipping.`);
+	}
+	if (field.pattern) {
+		const isObject = typeof field.pattern === "object";
+		const regexStr = isObject ? field.pattern.regex : field.pattern;
+		const message = isObject ? field.pattern.message : "Invalid format";
+		try {
+			rules.pattern = {
+				value: new RegExp(regexStr),
+				message
+			};
+		} catch {
+			console.warn(`[FormKit] Invalid regex pattern "${regexStr}" in field "${field.name}", skipping.`);
+		}
 	}
 	if (field.validate) rules.validate = field.validate;
 	return rules;
 }
+/** Returns true for fields that carry an `options` array (select, radio, etc.) */
+function isChoiceField(field) {
+	return [
+		"select",
+		"combobox",
+		"multiselect",
+		"dependentSelect",
+		"radio",
+		"checkbox"
+	].includes(field.type);
+}
+/** Returns true for free-text input fields */
+function isTextField(field) {
+	return [
+		"text",
+		"email",
+		"password",
+		"tel",
+		"phone",
+		"url",
+		"slug",
+		"textarea",
+		"rich-text"
+	].includes(field.type);
+}
+/** Returns true for numeric input fields */
+function isNumericField(field) {
+	return ["number", "rating"].includes(field.type);
+}
+/** Returns true for date / time fields */
+function isDateField(field) {
+	return [
+		"date",
+		"time",
+		"datetime"
+	].includes(field.type);
+}
+/** Returns true for structural fields that contain sub-fields (`itemFields`) */
+function isContainerField(field) {
+	return ["group", "array"].includes(field.type);
+}
+/** Returns true for array fields that render a repeatable list */
+function isArrayField(field) {
+	return field.type === "array";
+}
+/** Returns true for fields that load options asynchronously */
+function isDynamicField(field) {
+	return !!field.loadOptions;
+}
+/** Returns true for fields with conditional rendering */
+function isConditionalField(field) {
+	return field.condition !== void 0;
+}
+/**
+* Merge two or more schemas into one, concatenating their sections.
+*
+* @example
+* ```ts
+* const full = mergeSchemas(personalSchema, addressSchema, billingSchema);
+* ```
+*/
+function mergeSchemas(...schemas) {
+	return { sections: schemas.flatMap((s) => s.sections) };
+}
+/**
+* Add fields to a section identified by `sectionId`.
+* Returns a new schema — the original is not mutated.
+*
+* @example
+* ```ts
+* const extended = extendSection(schema, "personal", [
+*   field.text("middleName", "Middle Name"),
+* ]);
+* ```
+*/
+function extendSection(schema, sectionId, fields, position = "end") {
+	return {
+		...schema,
+		sections: schema.sections.map((section) => {
+			if (section.id !== sectionId) return section;
+			const existing = section.fields ?? [];
+			return {
+				...section,
+				fields: position === "start" ? [...fields, ...existing] : [...existing, ...fields]
+			};
+		})
+	};
+}
+/**
+* Create a new schema that includes only the named fields.
+*
+* @example
+* ```ts
+* const slim = pickFields(schema, ["email", "password"]);
+* ```
+*/
+function pickFields(schema, names) {
+	const nameSet = new Set(names);
+	return {
+		...schema,
+		sections: schema.sections.map((section) => ({
+			...section,
+			fields: (section.fields ?? []).filter((f) => nameSet.has(f.name))
+		})).filter((section) => (section.fields?.length ?? 0) > 0)
+	};
+}
+/**
+* Create a new schema that excludes the named fields.
+*
+* @example
+* ```ts
+* const withoutInternal = omitFields(schema, ["__id", "__createdAt"]);
+* ```
+*/
+function omitFields(schema, names) {
+	const nameSet = new Set(names);
+	return {
+		...schema,
+		sections: schema.sections.map((section) => ({
+			...section,
+			fields: (section.fields ?? []).filter((f) => !nameSet.has(f.name))
+		}))
+	};
+}
+/**
+* Collect every field from every section into a flat array.
+* Useful for validation, documentation, and AI schema introspection.
+*
+* @example
+* ```ts
+* const allFields = flattenSchema(schema);
+* const required = allFields.filter(f => f.required);
+* ```
+*/
+function flattenSchema(schema) {
+	return schema.sections.flatMap((s) => s.fields ?? []);
+}
 
 //#endregion
 //#region src/builders.ts
 /**
 * Type-safe field builder helpers for schema-driven forms.
 *
-* Provides shorthand methods for common field types with sensible defaults,
-* reducing boilerplate while maintaining full type safety.
+* All methods are generic over TFieldValues, defaulting to FieldValues (any string)
+* when no type argument is provided. Specify the generic to enforce that field
+* names are valid paths in your form values type.
+*
+* For fully-typed schemas where every field name is checked, prefer
+* `field.for<MyForm>()` which fixes the generic once for the whole schema:
 *
 * @example
 * ```ts
-* import { field, section } from '@classytic/formkit';
+* // Untyped — any string accepted (backwards compatible)
+* field.text("email", "Email")
+*
+* // Per-call generic — name is checked against MyForm
+* field.text<MyForm>("email", "Email")
 *
-* const schema = {
-*   sections: [
-*     section("personal", "Personal Info", [
-*       field.text("firstName", "First Name", { required: true }),
-*       field.email("email", "Email"),
-*       field.select("role", "Role", [
-*         { label: "Admin", value: "admin" },
-*         { label: "User", value: "user" },
-*       ]),
-*     ], { cols: 2 }),
-*   ],
-* };
+* // Typed factory — name checked on every call without repeating the generic
+* const f = field.for<MyForm>()
+* f.text("email", "Email")        // ✓
+* f.text("typo", "Email")         // ✗ TypeScript error
 * ```
 */
 const field = {
-	text: (name, label, props = {}) => ({
+	/** Text input field. */
+	text: (name, label, props) => ({
 		type: "text",
 		name,
 		label,
-		...props
+		...props ?? {}
 	}),
-	email: (name, label, props = {}) => ({
+	/** Email input field with default placeholder. */
+	email: (name, label, props) => ({
 		type: "email",
 		name,
 		label,
 		placeholder: "example@email.com",
-		...props
+		...props ?? {}
 	}),
-	url: (name, label, props = {}) => ({
+	/** URL input field with default placeholder. */
+	url: (name, label, props) => ({
 		type: "url",
 		name,
 		label,
 		placeholder: "https://example.com",
-		...props
+		...props ?? {}
 	}),
-	tel: (name, label, props = {}) => ({
+	/** Phone/tel input field with default placeholder. */
+	tel: (name, label, props) => ({
 		type: "tel",
 		name,
 		label,
 		placeholder: "+1 (555) 000-0000",
-		...props
+		...props ?? {}
 	}),
-	password: (name, label, props = {}) => ({
+	/** Password input field. */
+	password: (name, label, props) => ({
 		type: "password",
 		name,
 		label,
-		...props
+		...props ?? {}
 	}),
-	number: (name, label, props = {}) => ({
+	/** Number input field. No implicit `min` — pass `{ min }` to add one, so the
+	*  builder never injects validation the author didn't write (signed
+	*  quantities like deltas / temperatures stay valid). */
+	number: (name, label, props) => ({
 		type: "number",
 		name,
 		label,
-		min: 0,
-		...props
+		...props ?? {}
 	}),
-	textarea: (name, label, props = {}) => ({
+	/** Textarea field with default 3 rows. */
+	textarea: (name, label, props) => ({
 		type: "textarea",
 		name,
 		label,
 		rows: 3,
-		...props
+		...props ?? {}
 	}),
-	select: (name, label, options, props = {}) => ({
+	/** Select dropdown field. */
+	select: (name, label, options, props) => ({
 		type: "select",
 		name,
 		label,
 		options,
-		...props
+		...props ?? {}
 	}),
-	combobox: (name, label, options, props = {}) => ({
+	/** Searchable combobox field. */
+	combobox: (name, label, options, props) => ({
 		type: "combobox",
 		name,
 		label,
 		options,
-		...props
+		...props ?? {}
 	}),
-	multiselect: (name, label, options, props = {}) => ({
+	/** Multi-select field. */
+	multiselect: (name, label, options, props) => ({
 		type: "multiselect",
 		name,
 		label,
 		options,
 		placeholder: "Select options...",
-		...props
+		...props ?? {}
 	}),
-	dependentSelect: (name, label, props = {}) => ({
+	/** Dependent select field that reacts to parent field changes. */
+	dependentSelect: (name, label, props) => ({
 		type: "dependentSelect",
 		name,
 		label,
-		...props
+		...props ?? {}
 	}),
-	switch: (name, label, props = {}) => ({
+	/** Switch/toggle field. */
+	switch: (name, label, props) => ({
 		type: "switch",
 		name,
 		label,
-		...props
+		...props ?? {}
 	}),
-	boolean: (name, label, props = {}) => ({
+	/** Boolean field (alias for switch). */
+	boolean: (name, label, props) => ({
 		type: "switch",
 		name,
 		label,
-		...props
+		...props ?? {}
 	}),
-	checkbox: (name, label, props = {}) => ({
+	/** Checkbox field. */
+	checkbox: (name, label, props) => ({
 		type: "checkbox",
 		name,
 		label,
-		...props
+		...props ?? {}
 	}),
-	radio: (name, label, options, props = {}) => ({
+	/** Radio button group field. */
+	radio: (name, label, options, props) => ({
 		type: "radio",
 		name,
 		label,
 		options,
-		...props
+		...props ?? {}
 	}),
-	date: (name, label, props = {}) => ({
+	/** Date picker field. */
+	date: (name, label, props) => ({
 		type: "date",
 		name,
 		label,
-		...props
+		...props ?? {}
 	}),
-	tags: (name, label, props = {}) => ({
+	/** Tag input field. */
+	tags: (name, label, props) => ({
 		type: "tags",
 		name,
 		label,
 		placeholder: "Add tags...",
-		...props
+		...props ?? {}
 	}),
-	slug: (name, label, props = {}) => ({
+	/** Slug field. */
+	slug: (name, label, props) => ({
 		type: "slug",
 		name,
 		label,
 		placeholder: "my-page-slug",
-		...props
+		...props ?? {}
 	}),
-	file: (name, label, props = {}) => ({
+	/** File upload field. */
+	file: (name, label, props) => ({
 		type: "file",
 		name,
 		label,
-		...props
+		...props ?? {}
 	}),
-	hidden: (name, props = {}) => ({
+	/** Hidden field (no UI). */
+	hidden: (name, props) => ({
 		type: "hidden",
 		name,
-		...props
+		...props ?? {}
 	}),
-	group: (name, label, itemFields, props = {}) => ({
+	/**
+	* Group field for nested objects.
+	* Renders itemFields as a sub-grid. Child names are relative (e.g. "street"),
+	* FormGenerator prefixes them with the group name at render time.
+	*
+	* @example
+	* ```ts
+	* field.group("address", "Address", [
+	*   field.text("street", "Street"),
+	*   field.text("city", "City"),
+	* ], { cols: 2 })
+	* ```
+	*/
+	group: (name, label, itemFields, props) => ({
 		type: "group",
 		name,
 		label,
 		itemFields,
-		...props
+		...props ?? {}
 	}),
-	array: (name, label, itemFields, props = {}) => ({
+	/**
+	* Array/repeatable field backed by react-hook-form's useFieldArray.
+	*
+	* @example
+	* ```ts
+	* field.array("contacts", "Contacts", [
+	*   field.text("name", "Name"),
+	*   field.email("email", "Email"),
+	* ])
+	* ```
+	*/
+	array: (name, label, itemFields, props) => ({
 		type: "array",
 		name,
 		label,
 		itemFields,
-		...props
+		...props ?? {}
 	}),
-	custom: (name, label, render, props = {}) => ({
+	/**
+	* Custom field with a render function.
+	* Bypasses the component registry — full control over rendering.
+	*
+	* The render callback receives the complete `FieldComponentProps` including
+	* `fieldId`, `errorId`, `shouldShowError`, `error`, `rules`, and `control`.
+	*
+	* Use `shouldShowError` (not `!!error`) to drive `aria-invalid` and error
+	* visibility so timing mirrors the CSS `:user-invalid` pseudo-class.
+	*
+	* @example
+	* ```tsx
+	* field.custom("skills", "Skills", ({ control, shouldShowError, errorId, error, fieldId }) => (
+	*   <div>
+	*     <SkillSelector
+	*       id={fieldId}
+	*       control={control}
+	*       aria-invalid={shouldShowError || undefined}
+	*       aria-errormessage={shouldShowError ? errorId : undefined}
+	*     />
+	*     {shouldShowError && (
+	*       <p id={errorId} role="alert" className="text-sm text-destructive">
+	*         {error?.message}
+	*       </p>
+	*     )}
+	*   </div>
+	* ))
+	* ```
+	*/
+	custom: (name, label, render, props) => ({
 		type: "custom",
 		name,
 		label,
 		render,
-		...props
+		...props ?? {}
+	}),
+	/**
+	* Returns a typed field builder with `TFieldValues` fixed.
+	* Every field name is validated against `Path<TFieldValues>` at the call site —
+	* no need to repeat the generic on each individual builder call.
+	*
+	* @example
+	* ```ts
+	* interface ContactForm {
+	*   firstName: string;
+	*   email: string;
+	*   address: { street: string; city: string };
+	* }
+	*
+	* const f = field.for<ContactForm>()
+	*
+	* const schema = defineSchema<ContactForm>({
+	*   sections: [{
+	*     fields: [
+	*       f.text("firstName", "First Name"),     // ✓
+	*       f.email("email", "Email"),              // ✓
+	*       f.text("typo", "Label"),                // ✗ TypeScript error
+	*     ],
+	*   }],
+	* })
+	* ```
+	*/
+	for: () => ({
+		text: (name, label, props) => field.text(name, label, props),
+		email: (name, label, props) => field.email(name, label, props),
+		url: (name, label, props) => field.url(name, label, props),
+		tel: (name, label, props) => field.tel(name, label, props),
+		password: (name, label, props) => field.password(name, label, props),
+		number: (name, label, props) => field.number(name, label, props),
+		textarea: (name, label, props) => field.textarea(name, label, props),
+		select: (name, label, options, props) => field.select(name, label, options, props),
+		combobox: (name, label, options, props) => field.combobox(name, label, options, props),
+		multiselect: (name, label, options, props) => field.multiselect(name, label, options, props),
+		dependentSelect: (name, label, props) => field.dependentSelect(name, label, props),
+		switch: (name, label, props) => field.switch(name, label, props),
+		boolean: (name, label, props) => field.boolean(name, label, props),
+		checkbox: (name, label, props) => field.checkbox(name, label, props),
+		radio: (name, label, options, props) => field.radio(name, label, options, props),
+		date: (name, label, props) => field.date(name, label, props),
+		tags: (name, label, props) => field.tags(name, label, props),
+		slug: (name, label, props) => field.slug(name, label, props),
+		file: (name, label, props) => field.file(name, label, props),
+		hidden: (name, props) => field.hidden(name, props),
+		group: (name, label, itemFields, props) => field.group(name, label, itemFields, props),
+		array: (name, label, itemFields, props) => field.array(name, label, itemFields, props),
+		custom: (name, label, render, builderProps) => field.custom(name, label, render, builderProps)
 	})
 };
 /**
 * Create a section definition with sensible defaults.
 *
-* @param id - Unique section identifier
-* @param title - Section title
-* @param fields - Array of field definitions
-* @param props - Additional section configuration
-*
 * @example
 * ```ts
 * section("personal", "Personal Info", [
 *   field.text("name", "Name", { required: true }),
 *   field.email("email", "Email"),
-* ], { cols: 2, variant: "card" })
+* ], { cols: 2 })
 * ```
 */
 function section(id, title, fields, props = {}) {
@@ -411,6 +903,9 @@ function section(id, title, fields, props = {}) {
 /**
 * Create a section without a title (transparent section).
 * Useful for grouping fields without visual separation.
+*
+* Accepts `BaseField[]` (no generic) so mixed-type field arrays don't trigger
+* conflicting type inference across different field name generics.
 */
 function sectionUntitled(fields, props = {}) {
 	const { cols = 1, ...rest } = props;
@@ -423,4 +918,4 @@ function sectionUntitled(fields, props = {}) {
 }
 
 //#endregion
-export { buildValidationRules, cn, defineField, defineSchema, defineSection, evaluateCondition, extractDefaultValues, extractWatchNames, field, section, sectionUntitled };
+export { buildFieldDefaults, buildValidationRules, cn, defineField, defineSchema, defineSection, evaluateCondition, extendSection, extractDefaultValues, extractWatchNames, field, flattenSchema, isArrayField, isChoiceField, isConditionalField, isContainerField, isDateField, isDynamicField, isNumericField, isTextField, mergeDefaultValues, mergeSchemas, omitFields, pickFields, section, sectionUntitled, validateSchema };