@classytic/formkit 1.3.1 → 1.4.0

package/dist/index.mjs

@@ -1,7 +1,7 @@
 "use client";
-import { createContext, useContext, useEffect, useMemo, useRef, useState } from "react";
+import { PureComponent, createContext, memo, useContext, useEffect, useMemo, useRef, useState, useTransition } from "react";
 import { useFieldArray, useForm, useFormContext, useFormState, useWatch } from "react-hook-form";
-import { jsx, jsxs } from "react/jsx-runtime";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { clsx } from "clsx";
 import { twMerge } from "tailwind-merge";
 
@@ -93,7 +93,7 @@ function useFieldComponent(type, variant) {
 	if (defaultComponent && typeof defaultComponent === "function") return defaultComponent;
 	const textComponent = components["text"];
 	if (textComponent && typeof textComponent === "function") return textComponent;
-	if (process.env.NODE_ENV !== "production") {
+	if (typeof process === "undefined" || process.env["NODE_ENV"] !== "production") {
 		console.warn(`[FormKit] No component found for type "${type}"${variant ? ` (variant: "${variant}")` : ""}. Register a component for this type in your FormSystemProvider.`);
 		return MissingFieldComponent;
 	}
@@ -269,6 +269,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.
@@ -319,6 +327,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
@@ -332,11 +341,62 @@ 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[`${key}.${sub.name}`] = sub.defaultValue;
+			}
+		}
+	}
+	return defaults;
+}
+/**
+* Yield to the browser's main thread to keep the UI responsive.
+* Uses `scheduler.yield()` when available (Chromium 115+), falls back to a
+* zero-duration `setTimeout` which still gives the browser a chance to
+* process input, paint, and garbage-collect between chunks of work.
+*
+* @see https://developer.mozilla.org/en-US/docs/Web/API/Scheduler/yield
+*/
+async function yieldToMain() {
+	if (typeof globalThis !== "undefined" && "scheduler" in globalThis && typeof globalThis.scheduler.yield === "function") return globalThis.scheduler.yield();
+	return new Promise((resolve) => setTimeout(resolve, 0));
+}
+/**
+* Async version of `extractDefaultValues` for large schemas (50+ fields).
+* Yields to the main thread after each section so that the browser can
+* handle input events between chunks — keeping INP scores low.
+*
+* Use in `getDefaultValues` passed to `useForm` when the schema is known
+* to be large:
+*
+* @example
+* ```ts
+* const form = useForm({
+*   defaultValues: async () => extractDefaultValuesAsync(schema),
+* });
+* ```
+*/
+async function extractDefaultValuesAsync(schema) {
+	const defaults = {};
+	const BUDGET_MS = 50;
+	let deadline = performance.now() + BUDGET_MS;
+	for (const section of schema.sections) {
+		const prefix = section.nameSpace ? `${section.nameSpace}.` : "";
+		if (!section.fields) continue;
+		for (const field of section.fields) {
+			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;
 			}
 		}
+		if (performance.now() >= deadline) {
+			await yieldToMain();
+			deadline = performance.now() + BUDGET_MS;
+		}
 	}
 	return defaults;
 }
@@ -345,6 +405,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';
@@ -357,34 +420,220 @@ 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
 		};
-	} catch {
-		console.warn(`[FormKit] Invalid regex pattern "${field.pattern}" in field "${field.name}", skipping.`);
+	}
+	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
+		};
+	}
+	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 ?? []);
+}
+/**
+* Maps a server error response to react-hook-form field errors.
+*
+* Call this in your `onError` / `catch` handler after a failed API submission
+* to surface per-field server-side errors using the same UX as client validation.
+*
+* @param form - The `useForm` return value
+* @param errors - Map of field path → error message (dot-notation paths supported)
+*
+* @example
+* ```ts
+* async function onSubmit(data: FormValues) {
+*   try {
+*     await api.save(data);
+*   } catch (err) {
+*     if (err.fieldErrors) {
+*       applyServerErrors(form, err.fieldErrors);
+*       // { email: "Already taken", "address.zip": "Invalid ZIP" }
+*     }
+*   }
+* }
+* ```
+*/
+function applyServerErrors(form, errors) {
+	for (const [path, message] of Object.entries(errors)) form.setError(path, {
+		type: "server",
+		message
+	});
+}
 
 //#endregion
 //#region src/FormGenerator.tsx
@@ -424,14 +673,35 @@ function getNestedError(errors, path) {
 function prefixFields(fields, nameSpace) {
 	return fields.map((f) => ({
 		...f,
-		name: `${nameSpace}.${f.name}`,
-		itemFields: f.itemFields?.map((i) => ({
-			...i,
-			name: `${nameSpace}.${f.name}.${i.name}`
-		}))
+		name: `${nameSpace}.${f.name}`
 	}));
 }
 /**
+* Field-level error boundary. Catches render errors in individual field
+* components and shows a graceful fallback instead of crashing the whole form.
+*/
+var FormFieldErrorBoundary = class extends PureComponent {
+	state = { hasError: false };
+	static getDerivedStateFromError() {
+		return { hasError: true };
+	}
+	componentDidCatch(error, info) {
+		console.error(`[FormKit] Render error in field "${this.props.fieldName}":`, error, info);
+	}
+	render() {
+		if (this.state.hasError) return /* @__PURE__ */ jsxs("div", {
+			role: "alert",
+			className: "formkit-field-error-boundary rounded border border-red-300 bg-red-50 p-2 text-sm text-red-600",
+			children: [
+				"Failed to render field \"",
+				this.props.fieldName,
+				"\"."
+			]
+		});
+		return this.props.children;
+	}
+};
+/**
 * FormGenerator - Headless Form Generator Component
 *
 * Renders a form based on a schema definition, using components registered
@@ -476,14 +746,16 @@ function FormGenerator({ schema, control, disabled = false, variant, className,
 		}, section.id ?? `section-${index}`))
 	});
 }
-/**
-* Renders a single section with its fields.
-*/
-function SectionRenderer(props) {
+function SectionRendererImpl(props) {
 	if (props.section.condition) return /* @__PURE__ */ jsx(DynamicSectionRenderer, { ...props });
 	return /* @__PURE__ */ jsx(StaticSectionRenderer, { ...props });
 }
 /**
+* Memoized section renderer. Re-renders only when section config or
+* disabled/variant context changes — not on every form value change.
+*/
+const SectionRenderer = memo(SectionRendererImpl);
+/**
 * Section renderer that evaluates conditions reactively.
 * Scopes useWatch to only the fields referenced in the condition
 * to avoid re-rendering on every form change.
@@ -511,7 +783,7 @@ function StaticSectionRenderer({ section, control, disabled, variant }) {
 		if (section.nameSpace && section.fields) return prefixFields(section.fields, section.nameSpace);
 		return section.fields;
 	}, [section.nameSpace, section.fields]);
-	return /* @__PURE__ */ jsx(SectionLayout, {
+	const sectionNode = /* @__PURE__ */ jsx(SectionLayout, {
 		title: section.title,
 		description: section.description,
 		icon: section.icon,
@@ -519,6 +791,7 @@ function StaticSectionRenderer({ section, control, disabled, variant }) {
 		className: section.className,
 		collapsible: section.collapsible,
 		defaultCollapsed: section.defaultCollapsed,
+		deferRender: section.deferRender,
 		children: section.render ? section.render({
 			control,
 			disabled,
@@ -532,11 +805,17 @@ function StaticSectionRenderer({ section, control, disabled, variant }) {
 			variant: activeVariant
 		})
 	});
+	if (section.deferRender) return /* @__PURE__ */ jsx("div", {
+		className: "formkit-deferred-section",
+		style: {
+			contentVisibility: "auto",
+			containIntrinsicSize: "auto none auto 400px"
+		},
+		children: sectionNode
+	});
+	return sectionNode;
 }
-/**
-* Renders a grid of fields with specified column layout.
-*/
-function GridRenderer({ fields, cols = 1, gap, control, disabled, variant }) {
+function GridRendererImpl({ fields, cols = 1, gap, control, disabled, variant }) {
 	const GridLayout = useLayoutComponent("grid", variant);
 	if (!fields || fields.length === 0) return null;
 	return /* @__PURE__ */ jsx(GridLayout, {
@@ -551,60 +830,77 @@ function GridRenderer({ fields, cols = 1, gap, control, disabled, variant }) {
 	});
 }
 /**
-* Wraps individual fields.
-* If the field requires conditional logic or dynamic options, it uses the Dynamic wrapper.
-* Otherwise, it uses the Static wrapper, vastly improving performance by skipping `useWatch`.
+* Memoized grid renderer.
 */
-function FieldWrapper(props) {
+const GridRenderer = memo(GridRendererImpl);
+function FieldWrapperImpl(props) {
 	if (props.field.condition || props.field.loadOptions) return /* @__PURE__ */ jsx(DynamicFieldWrapper, { ...props });
 	if (props.field.render) return /* @__PURE__ */ jsx(RenderedFieldWrapper, { ...props });
 	return /* @__PURE__ */ jsx(StaticFieldWrapper, { ...props });
 }
+/**
+* Memoized field wrapper — the dispatch layer between schema fields and
+* their renderer. Re-renders only when the field config itself changes.
+*/
+const FieldWrapper = memo(FieldWrapperImpl);
 function RenderedFieldWrapper({ field, control, disabled, variant }) {
 	const fieldName = field.name;
 	const fieldId = toFieldId(fieldName);
+	const errorId = `${fieldId}-error`;
 	const activeVariant = field.variant ?? variant;
 	const isDisabled = disabled || field.disabled;
-	const { errors, dirtyFields, touchedFields } = useFormState({
+	const { errors, dirtyFields, touchedFields, isValidating, isSubmitted } = useFormState({
 		control,
 		name: fieldName
 	});
 	const fieldError = getNestedError(errors, fieldName);
 	const isDirty = Boolean(getNestedValue(dirtyFields, fieldName));
 	const isTouched = Boolean(getNestedValue(touchedFields, fieldName));
+	const shouldShowError = !!fieldError && (isTouched || isSubmitted);
 	const fieldState = useMemo(() => ({
 		invalid: !!fieldError,
 		isDirty,
 		isTouched,
-		isValidating: false,
+		isValidating,
+		isSubmitted,
 		error: fieldError
 	}), [
 		fieldError,
 		isDirty,
-		isTouched
+		isTouched,
+		isValidating,
+		isSubmitted
 	]);
-	return /* @__PURE__ */ jsx("div", {
-		className: cn("formkit-field", field.fullWidth && "col-span-full", field.className),
-		id: fieldId,
-		"data-formkit-field": fieldName,
-		"data-field-type": field.type,
-		children: field.render?.({
-			...field,
-			field,
-			control,
-			disabled: isDisabled,
-			variant: activeVariant,
-			error: fieldError,
-			fieldState,
-			fieldId,
-			isLoading: void 0
+	return /* @__PURE__ */ jsx(FormFieldErrorBoundary, {
+		fieldName,
+		children: /* @__PURE__ */ jsx("div", {
+			className: cn("formkit-field", field.fullWidth && "col-span-full", field.className),
+			"data-formkit-field": fieldName,
+			"data-field-type": field.type,
+			"data-invalid": shouldShowError ? "" : void 0,
+			"data-valid": !fieldError && isTouched ? "" : void 0,
+			"data-disabled": isDisabled ? "" : void 0,
+			children: field.render?.({
+				...field,
+				field,
+				control,
+				disabled: isDisabled,
+				variant: activeVariant,
+				error: fieldError,
+				fieldState,
+				fieldId,
+				errorId,
+				shouldShowError,
+				isLoading: void 0,
+				rules: buildValidationRules(field)
+			})
 		})
 	});
 }
 /**
 * Dynamic Field Wrapper
 * Conditionally calls `useWatch` to trigger re-renders only when form values change.
-* Can be optimized further by providing `watchNames` on the field.
+* Uses `useTransition` for async loadOptions to keep the UI responsive.
 */
 function DynamicFieldWrapper({ field, control, disabled, variant }) {
 	const ruleWatchNames = useMemo(() => extractWatchNames(field.condition), [field.condition]);
@@ -637,8 +933,10 @@ function DynamicFieldWrapper({ field, control, disabled, variant }) {
 		}), {});
 		return stableWatched;
 	}, [allWatchNames, stableWatched]);
+	const [, startTransition] = useTransition();
+	const [isLoading, setIsLoading] = useState(() => !!field.loadOptions);
 	const [options, setOptions] = useState(field.options || []);
-	const [isLoading, setIsLoading] = useState(false);
+	const [srAnnouncement, setSrAnnouncement] = useState("");
 	const timeoutRef = useRef(null);
 	useEffect(() => {
 		if (!field.loadOptions) return;
@@ -647,18 +945,24 @@ function DynamicFieldWrapper({ field, control, disabled, variant }) {
 			const res = field.loadOptions(watchedValues);
 			if (res instanceof Promise) {
 				setIsLoading(true);
-				res.then((newOptions) => {
-					if (isActive) setOptions(newOptions);
-				}).catch((err) => {
-					if (isActive) if (field.onLoadError) field.onLoadError(err);
-					else console.error("[FormKit] loadOptions error:", err);
-				}).finally(() => {
-					if (isActive) setIsLoading(false);
+				startTransition(async () => {
+					try {
+						const newOptions = await res;
+						if (isActive) {
+							setOptions(newOptions);
+							setIsLoading(false);
+							setSrAnnouncement(newOptions.length === 0 ? "No options available" : `${newOptions.length} option${newOptions.length === 1 ? "" : "s"} available`);
+						}
+					} catch (err) {
+						if (isActive) {
+							setIsLoading(false);
+							if (field.onLoadError) field.onLoadError(err);
+							else console.error("[FormKit] loadOptions error:", err);
+							setSrAnnouncement("Failed to load options");
+						}
+					}
 				});
-			} else {
-				setOptions(res);
-				setIsLoading(false);
-			}
+			} else setOptions(res);
 		};
 		if (field.debounceMs && field.debounceMs > 0) {
 			if (timeoutRef.current) clearTimeout(timeoutRef.current);
@@ -680,49 +984,60 @@ function DynamicFieldWrapper({ field, control, disabled, variant }) {
 	const loadingState = field.loadOptions ? isLoading : void 0;
 	const dynamicField = useMemo(() => ({
 		...field,
-		options: field.loadOptions ? options : field.options,
-		isLoading: loadingState
-	}), [
-		field,
-		options,
-		loadingState
-	]);
+		options: field.loadOptions ? options : field.options
+	}), [field, options]);
 	if (!evaluateCondition(field.condition, watchedValues)) return null;
-	return /* @__PURE__ */ jsx(StaticFieldWrapper, {
+	return /* @__PURE__ */ jsxs(Fragment, { children: [field.loadOptions && /* @__PURE__ */ jsx("span", {
+		role: "status",
+		"aria-live": "polite",
+		"aria-atomic": "true",
+		style: {
+			position: "absolute",
+			width: "1px",
+			height: "1px",
+			padding: 0,
+			margin: "-1px",
+			overflow: "hidden",
+			clip: "rect(0,0,0,0)",
+			whiteSpace: "nowrap",
+			border: 0
+		},
+		children: srAnnouncement
+	}), /* @__PURE__ */ jsx(StaticFieldWrapper, {
 		field: dynamicField,
 		control,
 		disabled,
 		variant,
 		isLoading: loadingState
-	});
+	})] });
 }
-/**
-* Static Field Wrapper
-* Handles rendering the actual component via the registry, or via a custom static `render`.
-* Does not use `useWatch` internally.
-*/
-function StaticFieldWrapper({ field, control, disabled, variant, isLoading }) {
+function StaticFieldWrapperImpl({ field, control, disabled, variant, isLoading }) {
 	const { components } = useFormSystem();
 	const fieldName = field.name;
-	const { errors, dirtyFields, touchedFields } = useFormState({
+	const { errors, dirtyFields, touchedFields, isValidating, isSubmitted } = useFormState({
 		control,
 		name: fieldName
 	});
 	const isDisabled = disabled || field.disabled;
 	const fieldId = toFieldId(fieldName);
+	const errorId = `${fieldId}-error`;
 	const fieldError = getNestedError(errors, fieldName);
 	const isDirty = Boolean(getNestedValue(dirtyFields, fieldName));
 	const isTouched = Boolean(getNestedValue(touchedFields, fieldName));
+	const shouldShowError = !!fieldError && (isTouched || isSubmitted);
 	const fieldState = useMemo(() => ({
 		invalid: !!fieldError,
 		isDirty,
 		isTouched,
-		isValidating: false,
+		isValidating,
+		isSubmitted,
 		error: fieldError
 	}), [
 		fieldError,
 		isDirty,
-		isTouched
+		isTouched,
+		isValidating,
+		isSubmitted
 	]);
 	const activeVariant = field.variant ?? variant;
 	if (!Boolean(components[field.type] || activeVariant && components[activeVariant] && typeof components[activeVariant] === "object" && components[activeVariant][field.type]) && field.itemFields && field.itemFields.length > 0) {
@@ -732,12 +1047,16 @@ function StaticFieldWrapper({ field, control, disabled, variant, isLoading }) {
 			disabled: isDisabled,
 			variant: activeVariant
 		});
+		const prefixedGroupFields = field.itemFields.map((f) => ({
+			...f,
+			name: `${fieldName}.${f.name}`
+		}));
 		return /* @__PURE__ */ jsx("div", {
 			className: cn("formkit-field-group", field.fullWidth && "col-span-full", field.className),
 			"data-formkit-field": fieldName,
 			"data-field-type": field.type,
 			children: /* @__PURE__ */ jsx(GridRenderer, {
-				fields: field.itemFields,
+				fields: prefixedGroupFields,
 				control,
 				disabled: isDisabled,
 				variant: activeVariant
@@ -746,7 +1065,7 @@ function StaticFieldWrapper({ field, control, disabled, variant, isLoading }) {
 	}
 	const FieldComponent = useFieldComponent(field.type, activeVariant);
 	if (!FieldComponent && !field.render) return null;
-	const fieldProps = {
+	const fieldProps = useMemo(() => ({
 		...field,
 		field,
 		control,
@@ -755,29 +1074,60 @@ function StaticFieldWrapper({ field, control, disabled, variant, isLoading }) {
 		error: fieldError,
 		fieldState,
 		fieldId,
+		errorId,
+		shouldShowError,
+		isLoading,
+		rules: buildValidationRules(field)
+	}), [
+		field,
+		control,
+		isDisabled,
+		activeVariant,
+		fieldError,
+		fieldState,
+		fieldId,
+		errorId,
+		shouldShowError,
 		isLoading
-	};
-	return /* @__PURE__ */ jsx("div", {
-		className: cn("formkit-field", field.fullWidth && "col-span-full", field.className),
-		id: fieldId,
-		"data-formkit-field": fieldName,
-		"data-field-type": field.type,
-		children: field.render ? field.render(fieldProps) : /* @__PURE__ */ jsx(FieldComponent, { ...fieldProps })
+	]);
+	return /* @__PURE__ */ jsx(FormFieldErrorBoundary, {
+		fieldName,
+		children: /* @__PURE__ */ jsx("div", {
+			className: cn("formkit-field", field.fullWidth && "col-span-full", field.className),
+			"data-formkit-field": fieldName,
+			"data-field-type": field.type,
+			"data-invalid": shouldShowError ? "" : void 0,
+			"data-valid": !fieldError && isTouched ? "" : void 0,
+			"data-loading": isLoading ? "" : void 0,
+			"data-disabled": isDisabled ? "" : void 0,
+			children: field.render ? field.render(fieldProps) : /* @__PURE__ */ jsx(FieldComponent, { ...fieldProps })
+		})
 	});
 }
+/**
+* Memoized static field wrapper — the hot path for all non-conditional fields.
+* Subscribes to `useFormState` scoped to a single field name so re-renders
+* are limited to changes in that specific field's validation state.
+*/
+const StaticFieldWrapper = memo(StaticFieldWrapperImpl);
 function ArrayFieldFallback({ field, control, disabled, variant }) {
 	const { fields, append, remove } = useFieldArray({
 		control,
 		name: field.name
 	});
+	const fieldId = toFieldId(field.name);
+	const labelId = field.label ? `${fieldId}-label` : void 0;
 	return /* @__PURE__ */ jsxs("div", {
+		role: "group",
+		"aria-labelledby": labelId,
 		className: cn("formkit-field-array flex flex-col gap-4", field.fullWidth && "col-span-full", field.className),
 		"data-formkit-field": field.name,
 		"data-field-type": "array",
 		children: [
-			/* @__PURE__ */ jsx("div", {
+			field.label && /* @__PURE__ */ jsx("div", {
 				className: "flex items-center justify-between",
-				children: field.label && /* @__PURE__ */ jsx("label", {
+				children: /* @__PURE__ */ jsx("span", {
+					id: labelId,
 					className: "font-semibold",
 					children: field.label
 				})
@@ -795,7 +1145,8 @@ function ArrayFieldFallback({ field, control, disabled, variant }) {
 				}), /* @__PURE__ */ jsx("button", {
 					type: "button",
 					onClick: () => remove(index),
-					className: "absolute top-2 right-2 text-red-500 hover:text-red-700 text-sm font-medium",
+					"aria-label": `Remove ${field.label ?? "item"} ${index + 1}`,
+					className: "absolute top-2 right-2 rounded text-red-500 hover:text-red-700 text-sm font-medium focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-red-500",
 					children: "Remove"
 				})]
 			}, item.id)),
@@ -809,7 +1160,7 @@ function ArrayFieldFallback({ field, control, disabled, variant }) {
 					append(defaults);
 				},
 				disabled,
-				className: "self-start mt-2 px-4 py-2 bg-blue-50 text-blue-600 rounded-md text-sm font-medium hover:bg-blue-100 disabled:opacity-50",
+				className: "self-start mt-2 px-4 py-2 bg-blue-50 text-blue-600 rounded-md text-sm font-medium hover:bg-blue-100 disabled:opacity-50 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-blue-500",
 				children: "+ Add Item"
 			})
 		]
@@ -821,195 +1172,314 @@ function ArrayFieldFallback({ field, control, disabled, variant }) {
 /**
 * 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 = {}) {
@@ -1025,6 +1495,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;
@@ -1060,10 +1533,23 @@ function sectionUntitled(fields, props = {}) {
 function useFormKit(options) {
 	const { schema, disabled, variant, className, defaultValues, ...formOptions } = options;
 	const schemaDefaults = useMemo(() => extractDefaultValues(schema), [schema]);
-	const mergedDefaults = useMemo(() => ({
-		...schemaDefaults,
-		...typeof defaultValues === "object" && defaultValues !== null ? defaultValues : {}
-	}), [schemaDefaults, defaultValues]);
+	const mergedDefaults = useMemo(() => {
+		if (typeof defaultValues === "function") {
+			const userFn = defaultValues;
+			const captured = schemaDefaults;
+			return async () => {
+				const userVals = await Promise.resolve(userFn());
+				return {
+					...captured,
+					...userVals
+				};
+			};
+		}
+		return {
+			...schemaDefaults,
+			...defaultValues != null ? defaultValues : {}
+		};
+	}, [schemaDefaults, defaultValues]);
 	const form = useForm({
 		...formOptions,
 		defaultValues: mergedDefaults
@@ -1085,4 +1571,4 @@ function useFormKit(options) {
 }
 
 //#endregion
-export { FieldWrapper, FormGenerator, FormSystemProvider, GridRenderer, SectionRenderer, buildValidationRules, cn, defineField, defineSchema, defineSection, evaluateCondition, extractDefaultValues, extractWatchNames, field, section, sectionUntitled, shallowEqual, useFieldComponent, useFormKit, useFormSystem, useLayoutComponent };
+export { FieldWrapper, FormGenerator, FormSystemProvider, GridRenderer, SectionRenderer, applyServerErrors, buildValidationRules, cn, defineField, defineSchema, defineSection, evaluateCondition, extendSection, extractDefaultValues, extractDefaultValuesAsync, extractWatchNames, field, flattenSchema, isArrayField, isChoiceField, isConditionalField, isContainerField, isDateField, isDynamicField, isNumericField, isTextField, mergeSchemas, omitFields, pickFields, section, sectionUntitled, shallowEqual, useFieldComponent, useFormKit, useFormSystem, useLayoutComponent };