@classytic/formkit 1.3.1 → 1.4.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
@@ -148,9 +157,11 @@ function extractDefaultValues(schema) {
 		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;
+			const key = `${prefix}${field.name}`;
+			if (field.defaultValue !== void 0) defaults[key] = field.defaultValue;
+			else if (field.type === "array") defaults[key] = [];
 			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;
+				for (const sub of field.itemFields) if (sub.defaultValue !== void 0) defaults[`${key}.${sub.name}`] = sub.defaultValue;
 			}
 		}
 	}
@@ -161,6 +172,9 @@ function extractDefaultValues(schema) {
 * 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 +187,505 @@ 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.required) rules.required = {
+		value: true,
+		message: `${field.label || field.name} is required`
 	};
-	if (field.min !== void 0) rules.min = {
-		value: field.min,
-		message: `Must be at least ${field.min}`
-	};
-	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
 		};
-	} catch {
-		console.warn(`[FormKit] Invalid regex pattern "${field.pattern}" in field "${field.name}", skipping.`);
+	}
+	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
+		};
+	}
+	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")
 *
-* 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 }),
-*   ],
-* };
+* // Per-call generic — name is checked against MyForm
+* field.text<MyForm>("email", "Email")
+*
+* // 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 with min: 0 default (overrideable via props). */
+	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 +701,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 +716,4 @@ function sectionUntitled(fields, props = {}) {
 }
 
 //#endregion
-export { buildValidationRules, cn, defineField, defineSchema, defineSection, evaluateCondition, extractDefaultValues, extractWatchNames, field, section, sectionUntitled };
+export { buildValidationRules, cn, defineField, defineSchema, defineSection, evaluateCondition, extendSection, extractDefaultValues, extractWatchNames, field, flattenSchema, isArrayField, isChoiceField, isConditionalField, isContainerField, isDateField, isDynamicField, isNumericField, isTextField, mergeSchemas, omitFields, pickFields, section, sectionUntitled };