@classytic/formkit 1.4.0 → 1.5.0

package/dist/index.mjs

@@ -1,10 +1,65 @@
 "use client";
 import { PureComponent, createContext, memo, useContext, useEffect, useMemo, useRef, useState, useTransition } from "react";
 import { useFieldArray, useForm, useFormContext, useFormState, useWatch } from "react-hook-form";
-import { Fragment, 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 (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;
-	}
-	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
 /**
@@ -338,20 +356,221 @@ 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) {
-			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;
-			}
-		}
+		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
@@ -383,16 +602,8 @@ async function extractDefaultValuesAsync(schema) {
 	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[`${key}.${sub.name}`] = sub.defaultValue;
-			}
-		}
+		collectExplicitDefaults(section.fields, section.nameSpace ?? "", defaults);
 		if (performance.now() >= deadline) {
 			await yieldToMain();
 			deadline = performance.now() + BUDGET_MS;
@@ -642,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.
 */
@@ -691,7 +927,13 @@ var FormFieldErrorBoundary = class extends PureComponent {
 	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",
+			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,
@@ -729,6 +971,12 @@ var FormFieldErrorBoundary = class extends PureComponent {
 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;
@@ -762,15 +1010,16 @@ const SectionRenderer = memo(SectionRendererImpl);
 */
 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;
@@ -875,6 +1124,8 @@ function RenderedFieldWrapper({ field, control, disabled, variant }) {
 		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,
@@ -916,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;
@@ -927,10 +1178,11 @@ 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();
@@ -938,17 +1190,41 @@ function DynamicFieldWrapper({ field, control, disabled, variant }) {
 	const [options, setOptions] = useState(field.options || []);
 	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);
 				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`);
@@ -970,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;
@@ -979,7 +1256,8 @@ 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(() => ({
@@ -1040,31 +1318,8 @@ function StaticFieldWrapperImpl({ field, control, disabled, variant, isLoading }
 		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) {
-		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),
-			"data-formkit-field": fieldName,
-			"data-field-type": field.type,
-			children: /* @__PURE__ */ jsx(GridRenderer, {
-				fields: prefixedGroupFields,
-				control,
-				disabled: isDisabled,
-				variant: activeVariant
-			})
-		});
-	}
+	const hasExplicitComponent = Boolean(components[field.type] || activeVariant && components[activeVariant] && typeof components[activeVariant] === "object" && components[activeVariant][field.type]);
 	const FieldComponent = useFieldComponent(field.type, activeVariant);
-	if (!FieldComponent && !field.render) return null;
 	const fieldProps = useMemo(() => ({
 		...field,
 		field,
@@ -1090,10 +1345,39 @@ function StaticFieldWrapperImpl({ field, control, disabled, variant, isLoading }
 		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: prefixedGroupFields,
+				control,
+				disabled: isDisabled,
+				variant: activeVariant
+			})
+		});
+	}
+	if (!FieldComponent && !field.render) return null;
 	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,
@@ -1120,20 +1404,30 @@ function ArrayFieldFallback({ field, control, disabled, variant }) {
 	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),
+		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: [
-			field.label && /* @__PURE__ */ jsx("div", {
-				className: "flex items-center justify-between",
-				children: /* @__PURE__ */ jsx("span", {
-					id: labelId,
-					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,
@@ -1144,23 +1438,25 @@ function ArrayFieldFallback({ field, control, disabled, variant }) {
 					variant
 				}), /* @__PURE__ */ jsx("button", {
 					type: "button",
+					className: "formkit-array-remove",
 					onClick: () => remove(index),
 					"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",
+					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 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-blue-500",
+				style: { alignSelf: "flex-start" },
 				children: "+ Add Item"
 			})
 		]
@@ -1232,12 +1528,13 @@ const field = {
 		label,
 		...props ?? {}
 	}),
-	/** Number input field with min: 0 default (overrideable via 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 ?? {}
 	}),
 	/** Textarea field with default 3 rows. */
@@ -1531,29 +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(() => {
 		if (typeof defaultValues === "function") {
 			const userFn = defaultValues;
 			const captured = schemaDefaults;
 			return async () => {
-				const userVals = await Promise.resolve(userFn());
-				return {
-					...captured,
-					...userVals
-				};
+				return mergeDefaultValues(captured, await Promise.resolve(userFn()) ?? {});
 			};
 		}
-		return {
-			...schemaDefaults,
-			...defaultValues != null ? defaultValues : {}
-		};
+		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,
@@ -1571,4 +1870,56 @@ function useFormKit(options) {
 }
 
 //#endregion
-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 };
+//#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 };