@classytic/formkit 1.3.1 → 1.5.0

package/dist/index.mjs

@@ -1,10 +1,65 @@
 "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 { clsx } from "clsx";
 import { twMerge } from "tailwind-merge";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 
+//#region src/utils.ts
+/**
+* Utility function to merge CSS classes with Tailwind CSS conflict resolution.
+*
+* Combines `clsx` for conditional class handling with `tailwind-merge`
+* for proper Tailwind CSS class conflict resolution.
+*
+* @param inputs - Class values to merge (strings, arrays, objects, or conditionals)
+* @returns Merged and deduplicated class string
+*
+* @example
+* ```tsx
+* // Basic usage
+* cn("px-2 py-1", "px-4") // "py-1 px-4"
+*
+* // Conditional classes
+* cn("base", isActive && "active", { "disabled": isDisabled })
+*
+* // Arrays
+* cn(["flex", "items-center"], "gap-2")
+* ```
+*/
+function cn(...inputs) {
+	return twMerge(clsx(inputs));
+}
+/**
+* Shallow equality check for arrays and primitives.
+* Used to stabilize useWatch output without JSON.stringify overhead.
+*/
+function shallowEqual(a, b) {
+	if (Object.is(a, b)) return true;
+	if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
+	if (Array.isArray(a) && Array.isArray(b)) {
+		if (a.length !== b.length) return false;
+		for (let i = 0; i < a.length; i++) if (!Object.is(a[i], b[i])) return false;
+		return true;
+	}
+	const keysA = Object.keys(a);
+	const keysB = Object.keys(b);
+	if (keysA.length !== keysB.length) return false;
+	for (const key of keysA) if (!Object.prototype.hasOwnProperty.call(b, key) || !Object.is(a[key], b[key])) return false;
+	return true;
+}
+/**
+* True outside production builds. Guards `typeof process` so bundler-less ESM
+* environments (no `process` global) don't throw a ReferenceError — they are
+* treated as dev, matching how missing-component reporting already behaved.
+*
+* @internal
+*/
+function isDev() {
+	return typeof process === "undefined" || process.env["NODE_ENV"] !== "production";
+}
+
+//#endregion
 //#region src/FormSystemContext.tsx
 const FormSystemContext = createContext(null);
 FormSystemContext.displayName = "FormSystemContext";
@@ -41,12 +96,17 @@ FormSystemContext.displayName = "FormSystemContext";
 * }
 * ```
 */
-function FormSystemProvider({ components, layouts, children }) {
+function FormSystemProvider({ components, layouts, onMissingComponent, children }) {
 	return /* @__PURE__ */ jsx(FormSystemContext, {
 		value: useMemo(() => ({
 			components: components ?? {},
-			layouts: layouts ?? {}
-		}), [components, layouts]),
+			layouts: layouts ?? {},
+			onMissingComponent
+		}), [
+			components,
+			layouts,
+			onMissingComponent
+		]),
 		children
 	});
 }
@@ -73,11 +133,16 @@ function useFormSystem() {
 * 1. Variant-specific component: `components[variant][type]`
 * 2. Type-specific component: `components[type]`
 * 3. Default component: `components["default"]`
-* 4. Text fallback: `components["text"]`
+*
+* There is intentionally NO "text" fallback: rendering a text input for an
+* unregistered `date`/`switch`/etc. is a silent wrong-widget bug. A missing
+* registration instead renders a visible placeholder (`MissingFieldComponent`)
+* — in production too — and notifies `onMissingComponent`, so the gap is
+* observable rather than a mystery empty box.
 *
 * @param type - Field type identifier
 * @param variant - Optional variant name
-* @returns Field component or fallback
+* @returns Field component or the visible placeholder
 *
 * @internal
 */
@@ -91,13 +156,7 @@ function useFieldComponent(type, variant) {
 	if (typeComponent && typeof typeComponent === "function") return typeComponent;
 	const defaultComponent = components["default"];
 	if (defaultComponent && typeof defaultComponent === "function") return defaultComponent;
-	const textComponent = components["text"];
-	if (textComponent && typeof textComponent === "function") return textComponent;
-	if (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;
-	}
-	return NullComponent;
+	return MissingFieldComponent;
 }
 /**
 * Hook to get a layout component by type and optional variant.
@@ -136,81 +195,40 @@ function DefaultLayout({ children, className }) {
 		children
 	});
 }
+const reportedMissing = /* @__PURE__ */ new Set();
 /**
-* Null component for production fallback.
-*/
-function NullComponent() {
-	return null;
-}
-/**
-* Development placeholder for missing field components.
+* Visible placeholder for a field whose `type` has no registered component.
+* Rendered in dev AND prod (a silent drop hides bugs). Uses inline styles so it
+* looks the same without the host's Tailwind. Reports via an effect (dev warn +
+* `onMissingComponent`), keeping the render pure.
 */
 function MissingFieldComponent({ field }) {
+	const { onMissingComponent } = useFormSystem();
+	useEffect(() => {
+		if (reportedMissing.has(field.type)) return;
+		reportedMissing.add(field.type);
+		if (isDev()) console.warn(`[FormKit] No component registered for field type "${field.type}". Rendered a placeholder — register it in your FormSystemProvider.`);
+		onMissingComponent?.(field.type);
+	}, [field.type, onMissingComponent]);
 	return /* @__PURE__ */ jsxs("div", {
+		role: "status",
+		className: "formkit-missing-field",
 		style: {
-			color: "#dc2626",
 			padding: "8px 12px",
-			border: "1px dashed #dc2626",
-			borderRadius: "4px",
+			border: "1px dashed currentColor",
+			borderRadius: "6px",
 			fontSize: "12px",
-			fontFamily: "monospace",
-			backgroundColor: "#fef2f2"
+			fontFamily: "ui-monospace, SFMono-Regular, monospace",
+			opacity: .75
 		},
 		children: [
-			"Missing component: ",
+			"Unsupported field type ",
 			/* @__PURE__ */ jsx("strong", { children: field.type }),
-			" (field: ",
-			field.name,
-			")"
+			field.name ? ` (“${field.name}”)` : ""
 		]
 	});
 }
 
-//#endregion
-//#region src/utils.ts
-/**
-* Utility function to merge CSS classes with Tailwind CSS conflict resolution.
-*
-* Combines `clsx` for conditional class handling with `tailwind-merge`
-* for proper Tailwind CSS class conflict resolution.
-*
-* @param inputs - Class values to merge (strings, arrays, objects, or conditionals)
-* @returns Merged and deduplicated class string
-*
-* @example
-* ```tsx
-* // Basic usage
-* cn("px-2 py-1", "px-4") // "py-1 px-4"
-*
-* // Conditional classes
-* cn("base", isActive && "active", { "disabled": isDisabled })
-*
-* // Arrays
-* cn(["flex", "items-center"], "gap-2")
-* ```
-*/
-function cn(...inputs) {
-	return twMerge(clsx(inputs));
-}
-/**
-* Shallow equality check for arrays and primitives.
-* Used to stabilize useWatch output without JSON.stringify overhead.
-*/
-function shallowEqual(a, b) {
-	if (Object.is(a, b)) return true;
-	if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
-	if (Array.isArray(a) && Array.isArray(b)) {
-		if (a.length !== b.length) return false;
-		for (let i = 0; i < a.length; i++) if (!Object.is(a[i], b[i])) return false;
-		return true;
-	}
-	const keysA = Object.keys(a);
-	const keysB = Object.keys(b);
-	if (keysA.length !== keysB.length) return false;
-	for (const key of keysA) if (!Object.prototype.hasOwnProperty.call(b, key) || !Object.is(a[key], b[key])) return false;
-	return true;
-}
-
 //#endregion
 //#region src/schema.ts
 /**
@@ -269,6 +287,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 +345,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
@@ -329,13 +356,257 @@ 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;
+}
+/**
+* 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) {
+		if (!section.fields) continue;
+		collectExplicitDefaults(section.fields, section.nameSpace ?? "", defaults);
+		if (performance.now() >= deadline) {
+			await yieldToMain();
+			deadline = performance.now() + BUDGET_MS;
 		}
 	}
 	return defaults;
@@ -345,6 +616,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 +631,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
+		};
+	}
+	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 ?? []);
+}
+/**
+* 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
@@ -393,6 +853,31 @@ function toFieldId(name) {
 	return `formkit-field-${name.replace(/[.[\]]/g, "-")}`;
 }
 /**
+* The `data-col-span` hook for a field. `fullWidth` wins (it spans the whole
+* row via `col-span-full`); otherwise a `colSpan >= 2` is surfaced as a data
+* attribute for the consumer's stylesheet to interpret responsively. We emit a
+* data attribute (not an inline `grid-column`) on purpose: an inline span on a
+* single-column mobile grid creates an empty implicit track that steals a `gap`
+* gutter, narrowing every field in that grid. A stylesheet can scope the span
+* to the breakpoints where the extra columns actually exist.
+*/
+function fieldColSpan(field) {
+	if (field.fullWidth || !field.colSpan || field.colSpan < 2) return void 0;
+	return field.colSpan;
+}
+/**
+* Inline `grid-column: 1 / -1` for `fullWidth` fields. The renderer also sets
+* the `col-span-full` class, but that Tailwind class only exists if the host's
+* content scan reaches it — which it won't for a published dist in
+* `node_modules`. This inline style makes full-width **load-bearing layout**
+* work regardless of the consumer's Tailwind setup. `1 / -1` spans only the
+* existing explicit columns, so it collapses safely to full width on a
+* single-column mobile grid (no implicit track / gap artifact).
+*/
+function fullWidthStyle(field) {
+	return field.fullWidth ? { gridColumn: "1 / -1" } : void 0;
+}
+/**
 * Get nested value from an object using dot-notation path.
 * Handles array indices: "items.0.name" resolves through arrays correctly.
 */
@@ -424,14 +909,41 @@ 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",
+			style: {
+				border: "1px solid currentColor",
+				borderRadius: "6px",
+				padding: "8px 12px",
+				fontSize: "13px"
+			},
+			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
@@ -459,6 +971,12 @@ function prefixFields(fields, nameSpace) {
 function FormGenerator({ schema, control, disabled = false, variant, className, ref }) {
 	const formContext = useFormContext();
 	const activeControl = control ?? formContext?.control;
+	useEffect(() => {
+		if (!isDev()) return;
+		if (!schema?.sections) return;
+		const issues = validateSchema(schema);
+		if (issues.length > 0) console.warn(`[FormKit] Schema has ${issues.length} issue(s):`, issues.map((x) => `${x.severity.toUpperCase()} ${x.path}: ${x.message}`));
+	}, [schema]);
 	if (!activeControl) {
 		console.warn("[FormKit] FormGenerator requires a `control` prop or to be wrapped in a <FormProvider>.");
 		return null;
@@ -476,29 +994,32 @@ 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.
 */
 function DynamicSectionRenderer(props) {
 	const conditionWatchNames = useMemo(() => extractWatchNames(props.section.condition), [props.section.condition]);
-	const watchedRaw = conditionWatchNames.length > 0 ? useWatch({
+	const watchedRaw = useWatch({
 		control: props.control,
-		name: conditionWatchNames
-	}) : useWatch({ control: props.control });
+		name: conditionWatchNames.length > 0 ? conditionWatchNames : void 0
+	});
 	const sectionValues = useMemo(() => {
-		if (conditionWatchNames.length > 0 && Array.isArray(watchedRaw)) return conditionWatchNames.reduce((acc, name, i) => ({
-			...acc,
-			[name]: watchedRaw[i]
-		}), {});
+		if (conditionWatchNames.length > 0 && Array.isArray(watchedRaw)) {
+			const nested = {};
+			conditionWatchNames.forEach((name, i) => assignPath(nested, name, watchedRaw[i]));
+			return nested;
+		}
 		return watchedRaw;
 	}, [conditionWatchNames, watchedRaw]);
 	if (!evaluateCondition(props.section.condition, sectionValues)) return null;
@@ -511,7 +1032,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 +1040,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 +1054,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 +1079,79 @@ 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),
+			style: fullWidthStyle(field),
+			"data-col-span": fieldColSpan(field),
+			"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]);
@@ -620,10 +1167,10 @@ function DynamicFieldWrapper({ field, control, disabled, variant }) {
 		allWatchNamesRef.current = next;
 		return next;
 	}, [explicitWatchNames, ruleWatchNames]);
-	const watchedRaw = allWatchNames.length > 0 ? useWatch({
+	const watchedRaw = useWatch({
 		control,
-		name: allWatchNames
-	}) : useWatch({ control });
+		name: allWatchNames.length > 0 ? allWatchNames : void 0
+	});
 	const prevWatchedRef = useRef(watchedRaw);
 	const stableWatched = useMemo(() => {
 		if (shallowEqual(prevWatchedRef.current, watchedRaw)) return prevWatchedRef.current;
@@ -631,34 +1178,67 @@ function DynamicFieldWrapper({ field, control, disabled, variant }) {
 		return watchedRaw;
 	}, [watchedRaw]);
 	const watchedValues = useMemo(() => {
-		if (allWatchNames.length > 0 && Array.isArray(stableWatched)) return allWatchNames.reduce((acc, name, i) => ({
-			...acc,
-			[name]: stableWatched[i]
-		}), {});
+		if (allWatchNames.length > 0 && Array.isArray(stableWatched)) {
+			const nested = {};
+			allWatchNames.forEach((name, i) => assignPath(nested, name, stableWatched[i]));
+			return nested;
+		}
 		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);
+	const optionsCacheRef = useRef(/* @__PURE__ */ new Map());
+	const loadOptionsWarnedRef = useRef(false);
 	useEffect(() => {
 		if (!field.loadOptions) return;
+		if (isDev() && allWatchNames.length === 0 && !loadOptionsWarnedRef.current) {
+			loadOptionsWarnedRef.current = true;
+			console.warn(`[FormKit] Field "${String(field.name)}" uses loadOptions without watchNames, so it subscribes to the entire form and refetches on any change. Add watchNames to scope it.`);
+		}
 		let isActive = true;
+		const controller = new AbortController();
 		const executeLoad = () => {
-			const res = field.loadOptions(watchedValues);
+			const cacheKey = field.cacheOptions ? JSON.stringify(watchedValues ?? null) : null;
+			if (cacheKey !== null) {
+				const cached = optionsCacheRef.current.get(cacheKey);
+				if (cached) {
+					setOptions(cached);
+					setIsLoading(false);
+					return;
+				}
+			}
+			const res = field.loadOptions(watchedValues, { signal: controller.signal });
 			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) {
+							if (cacheKey !== null) {
+								const cache = optionsCacheRef.current;
+								cache.set(cacheKey, newOptions);
+								if (cache.size > 50) {
+									const oldest = cache.keys().next().value;
+									if (oldest !== void 0) cache.delete(oldest);
+								}
+							}
+							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);
@@ -666,6 +1246,7 @@ function DynamicFieldWrapper({ field, control, disabled, variant }) {
 		} else executeLoad();
 		return () => {
 			isActive = false;
+			controller.abort();
 			if (timeoutRef.current) {
 				clearTimeout(timeoutRef.current);
 				timeoutRef.current = null;
@@ -675,115 +1256,178 @@ function DynamicFieldWrapper({ field, control, disabled, variant }) {
 		watchedValues,
 		field.loadOptions,
 		field.debounceMs,
-		field.onLoadError
+		field.onLoadError,
+		field.cacheOptions
 	]);
 	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) {
+	const hasExplicitComponent = Boolean(components[field.type] || activeVariant && components[activeVariant] && typeof components[activeVariant] === "object" && components[activeVariant][field.type]);
+	const FieldComponent = useFieldComponent(field.type, activeVariant);
+	const fieldProps = useMemo(() => ({
+		...field,
+		field,
+		control,
+		disabled: isDisabled,
+		variant: activeVariant,
+		error: fieldError,
+		fieldState,
+		fieldId,
+		errorId,
+		shouldShowError,
+		isLoading,
+		rules: buildValidationRules(field)
+	}), [
+		field,
+		control,
+		isDisabled,
+		activeVariant,
+		fieldError,
+		fieldState,
+		fieldId,
+		errorId,
+		shouldShowError,
+		isLoading
+	]);
+	if (field.type === "hidden" && !hasExplicitComponent && !field.render) return null;
+	if (!hasExplicitComponent && field.itemFields && field.itemFields.length > 0) {
 		if (field.type === "array") return /* @__PURE__ */ jsx(ArrayFieldFallback, {
 			field,
 			control,
 			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),
+			style: fullWidthStyle(field),
+			"data-col-span": fieldColSpan(field),
 			"data-formkit-field": fieldName,
 			"data-field-type": field.type,
 			children: /* @__PURE__ */ jsx(GridRenderer, {
-				fields: field.itemFields,
+				fields: prefixedGroupFields,
 				control,
 				disabled: isDisabled,
 				variant: activeVariant
 			})
 		});
 	}
-	const FieldComponent = useFieldComponent(field.type, activeVariant);
 	if (!FieldComponent && !field.render) return null;
-	const fieldProps = {
-		...field,
-		field,
-		control,
-		disabled: isDisabled,
-		variant: activeVariant,
-		error: fieldError,
-		fieldState,
-		fieldId,
-		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),
+			style: fullWidthStyle(field),
+			"data-col-span": fieldColSpan(field),
+			"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", {
-		className: cn("formkit-field-array flex flex-col gap-4", field.fullWidth && "col-span-full", field.className),
+		role: "group",
+		"aria-labelledby": labelId,
+		className: cn("formkit-field-array", field.className),
+		style: {
+			display: "flex",
+			flexDirection: "column",
+			gap: "1rem",
+			...fullWidthStyle(field)
+		},
+		"data-col-span": fieldColSpan(field),
 		"data-formkit-field": field.name,
 		"data-field-type": "array",
 		children: [
-			/* @__PURE__ */ jsx("div", {
-				className: "flex items-center justify-between",
-				children: field.label && /* @__PURE__ */ jsx("label", {
-					className: "font-semibold",
-					children: field.label
-				})
+			field.label && /* @__PURE__ */ jsx("span", {
+				id: labelId,
+				style: { fontWeight: 600 },
+				children: field.label
 			}),
 			fields.map((item, index) => /* @__PURE__ */ jsxs("div", {
-				className: "relative formkit-array-item border p-4 rounded-md",
+				className: "formkit-array-item",
+				style: {
+					position: "relative",
+					border: "1px solid currentColor",
+					borderRadius: "6px",
+					padding: "1rem"
+				},
 				children: [/* @__PURE__ */ jsx(GridRenderer, {
 					fields: field.itemFields?.map((f) => ({
 						...f,
@@ -794,22 +1438,25 @@ function ArrayFieldFallback({ field, control, disabled, variant }) {
 					variant
 				}), /* @__PURE__ */ jsx("button", {
 					type: "button",
+					className: "formkit-array-remove",
 					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}`,
+					style: {
+						position: "absolute",
+						top: "0.5rem",
+						right: "0.5rem"
+					},
 					children: "Remove"
 				})]
 			}, item.id)),
 			/* @__PURE__ */ jsx("button", {
 				type: "button",
+				className: "formkit-array-add",
 				onClick: () => {
-					const defaults = {};
-					if (field.itemFields) {
-						for (const f of field.itemFields) if (f.defaultValue !== void 0) defaults[f.name] = f.defaultValue;
-					}
-					append(defaults);
+					append(buildFieldDefaults(field.itemFields));
 				},
 				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",
+				style: { alignSelf: "flex-start" },
 				children: "+ Add Item"
 			})
 		]
@@ -821,195 +1468,315 @@ 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. 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 = {}) {
@@ -1025,6 +1792,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;
@@ -1058,16 +1828,31 @@ function sectionUntitled(fields, props = {}) {
 * ```
 */
 function useFormKit(options) {
-	const { schema, disabled, variant, className, defaultValues, ...formOptions } = options;
+	const { schema, disabled, variant, className, defaultValues, resetOnSchemaChange, ...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 () => {
+				return mergeDefaultValues(captured, await Promise.resolve(userFn()) ?? {});
+			};
+		}
+		return mergeDefaultValues(schemaDefaults, defaultValues != null ? defaultValues : {});
+	}, [schemaDefaults, defaultValues]);
 	const form = useForm({
 		...formOptions,
 		defaultValues: mergedDefaults
 	});
+	const isFirstSchemaRef = useRef(true);
+	useEffect(() => {
+		if (isFirstSchemaRef.current) {
+			isFirstSchemaRef.current = false;
+			return;
+		}
+		if (!resetOnSchemaChange || typeof mergedDefaults === "function") return;
+		form.reset(mergedDefaults);
+	}, [schema]);
 	const generatorProps = useMemo(() => ({
 		schema,
 		control: form.control,
@@ -1085,4 +1870,56 @@ 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 };
+//#region src/focus.ts
+/**
+* Focus (and scroll to) the first field currently shown as invalid.
+*
+* It queries the rendered `[data-formkit-field][data-invalid]` wrapper — which
+* `FormGenerator` marks once errors are visible (after touch / submit) — so it
+* targets the first error in **visual order**, not react-hook-form's error-key
+* order (which isn't guaranteed to match the layout). Wire it into your submit's
+* invalid handler:
+*
+* ```ts
+* form.handleSubmit(onValid, () => focusFirstError());
+* ```
+*
+* **Timing:** react-hook-form calls the invalid handler *before* React commits
+* the re-render that sets `data-invalid` on the wrappers, so on the very first
+* invalid submit a synchronous query finds nothing. When the immediate attempt
+* misses, this retries on the next two animation frames (the commit lands
+* before the next paint), so the plain wiring above Just Works.
+*
+* @param root  Optional container to search within (defaults to `document`).
+* @returns `true` if a field was focused immediately; `false` if not found yet
+*          (a deferred retry may still focus it on the next frame).
+*/
+function focusFirstError(root) {
+	const scope = root ?? (typeof document !== "undefined" ? document : null);
+	if (!scope) return false;
+	if (attemptFocus(scope)) return true;
+	if (typeof requestAnimationFrame === "function") requestAnimationFrame(() => {
+		if (attemptFocus(scope)) return;
+		requestAnimationFrame(() => {
+			attemptFocus(scope);
+		});
+	});
+	return false;
+}
+/** Single synchronous query-and-focus attempt. */
+function attemptFocus(scope) {
+	const wrapper = scope.querySelector("[data-formkit-field][data-invalid]");
+	if (!wrapper) return false;
+	const target = wrapper.querySelector("input, select, textarea, [contenteditable='true'], [tabindex]:not([tabindex='-1'])") ?? wrapper;
+	target.scrollIntoView({
+		behavior: "smooth",
+		block: "center"
+	});
+	try {
+		target.focus({ preventScroll: true });
+	} catch {}
+	return true;
+}
+
+//#endregion
+export { FieldWrapper, FormGenerator, FormSystemProvider, GridRenderer, SectionRenderer, applyServerErrors, buildFieldDefaults, buildValidationRules, cn, defineField, defineSchema, defineSection, evaluateCondition, extendSection, extractDefaultValues, extractDefaultValuesAsync, extractWatchNames, field, flattenSchema, focusFirstError, isArrayField, isChoiceField, isConditionalField, isContainerField, isDateField, isDynamicField, isNumericField, isTextField, mergeDefaultValues, mergeSchemas, omitFields, pickFields, section, sectionUntitled, shallowEqual, useFieldComponent, useFormKit, useFormSystem, useLayoutComponent, validateSchema };