@classytic/formkit 1.4.0 → 1.5.0

package/dist/server.d.mts

@@ -161,6 +161,13 @@ interface BaseField<TFieldValues extends FieldValues = FieldValues> {
   variant?: Variant;
   /** Whether field should span full width in grid */
   fullWidth?: boolean;
+  /**
+   * Span N columns of the section grid (e.g. `2` of a 3-col section). `1` (or
+   * unset) is the default single cell; `fullWidth` still means "span the whole
+   * row" and takes precedence. Applied as an inline `grid-column: span N` so it
+   * works regardless of the host's Tailwind content scan.
+   */
+  colSpan?: number;
   /** Custom CSS class name */
   className?: string;
   /**
@@ -222,13 +229,33 @@ interface BaseField<TFieldValues extends FieldValues = FieldValues> {
   /**
    * Dynamic options loaded based on current form values.
    * Useful for dependent selects (e.g., state depends on country).
+   *
+   * Receives an `AbortSignal` in the second arg — forward it to `fetch` (or
+   * abort your own request on it) so a superseded / unmounted load is cancelled
+   * instead of racing to completion:
+   *
+   * ```ts
+   * loadOptions: (values, { signal }) =>
+   *   fetch(`/api/cities?country=${values.country}`, { signal }).then(r => r.json())
+   * ```
    */
-  loadOptions?: (formValues: Partial<TFieldValues>) => Promise<(FieldOption | FieldOptionGroup)[]> | (FieldOption | FieldOptionGroup)[];
+  loadOptions?: (formValues: Partial<TFieldValues>, options?: {
+    signal: AbortSignal;
+  }) => Promise<(FieldOption | FieldOptionGroup)[]> | (FieldOption | FieldOptionGroup)[];
   /**
    * Error callback for loadOptions failures.
    * Called when loadOptions rejects. Defaults to console.error.
    */
   onLoadError?: (error: unknown) => void;
+  /**
+   * Memoize async `loadOptions` results per set of watched values, so toggling
+   * a dependency back and forth (e.g. re-selecting a country) reuses the last
+   * fetch instead of hitting the API again. Off by default — enable only when
+   * the options are stable for a given input, since the cache lives for the
+   * field's lifetime and won't see server-side changes. Bounded (LRU-ish) so it
+   * can't grow without limit.
+   */
+  cacheOptions?: boolean;
   /**
    * Sub-fields for `group` and `array` field types.
    *
@@ -591,6 +618,54 @@ declare function defineSection<TFieldValues extends FieldValues = FieldValues>(s
  * ```
  */
 declare function extractDefaultValues<TFieldValues extends FieldValues = FieldValues>(schema: FormSchema<TFieldValues>): Partial<TFieldValues>;
+interface SchemaIssue {
+  /** Where the issue is, e.g. `sections[0].fields[2]` or `sections[1]`. */
+  path: string;
+  code: "missing-name" | "missing-type" | "duplicate-name" | "itemfields-on-noncontainer" | "empty-container" | "unknown-operator";
+  /** `error` = will misbehave at runtime; `warning` = suspicious but tolerated. */
+  severity: "error" | "warning";
+  message: string;
+}
+/**
+ * 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.
+ */
+declare function validateSchema(schema: FormSchema): SchemaIssue[];
+/**
+ * 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).
+ */
+declare function buildFieldDefaults(fields: BaseField[] | undefined): Record<string, unknown>;
+/**
+ * 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);
+ * ```
+ */
+declare function mergeDefaultValues(base: Record<string, unknown>, override: Record<string, unknown>): Record<string, unknown>;
 /**
  * Generates react-hook-form `RegisterOptions`-compatible validation rules
  * from a field's schema props. Maps `required`, `min`, `max`, `minLength`,
@@ -719,7 +794,10 @@ declare const field: {
   email: <T extends FieldValues = FieldValues>(name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>; /** URL input field with default placeholder. */
   url: <T extends FieldValues = FieldValues>(name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>; /** Phone/tel input field with default placeholder. */
   tel: <T extends FieldValues = FieldValues>(name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>; /** Password input field. */
-  password: <T extends FieldValues = FieldValues>(name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>; /** Number input field with min: 0 default (overrideable via props). */
+  password: <T extends FieldValues = FieldValues>(name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>;
+  /** 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: <T extends FieldValues = FieldValues>(name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>; /** Textarea field with default 3 rows. */
   textarea: <T extends FieldValues = FieldValues>(name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>; /** Select dropdown field. */
   select: <T extends FieldValues = FieldValues>(name: Path<T>, label: string, options: (FieldOption | FieldOptionGroup)[], props?: FieldProps<T>) => BaseField<T>; /** Searchable combobox field. */
@@ -864,4 +942,4 @@ declare function section<TFieldValues extends FieldValues = FieldValues>(id: str
  */
 declare function sectionUntitled(fields: BaseField[], props?: Omit<SectionProps, "variant">): Section;
 //#endregion
-export { type BaseField, type ClassValue, type Condition, type ConditionConfig, type ConditionRule, type DefaultLayoutProps, type DefineField, type FieldMeta, type FieldOption, type FieldOptionGroup, type FieldType, type FormSchema, type GridLayoutProps, type InferSchemaValues, type LayoutComponentProps, type LayoutType, type PatternRuleObject, type SchemaFieldNames, type Section, type SectionLayoutProps, type SectionRenderProps, type ValidationRuleObject, type Variant, buildValidationRules, cn, defineField, defineSchema, defineSection, evaluateCondition, extendSection, extractDefaultValues, extractWatchNames, field, flattenSchema, isArrayField, isChoiceField, isConditionalField, isContainerField, isDateField, isDynamicField, isNumericField, isTextField, mergeSchemas, omitFields, pickFields, section, sectionUntitled };
+export { type BaseField, type ClassValue, type Condition, type ConditionConfig, type ConditionRule, type DefaultLayoutProps, type DefineField, type FieldMeta, type FieldOption, type FieldOptionGroup, type FieldType, type FormSchema, type GridLayoutProps, type InferSchemaValues, type LayoutComponentProps, type LayoutType, type PatternRuleObject, type SchemaFieldNames, type SchemaIssue, type Section, type SectionLayoutProps, type SectionRenderProps, type ValidationRuleObject, type Variant, buildFieldDefaults, buildValidationRules, cn, defineField, defineSchema, defineSection, evaluateCondition, extendSection, extractDefaultValues, extractWatchNames, field, flattenSchema, isArrayField, isChoiceField, isConditionalField, isContainerField, isDateField, isDynamicField, isNumericField, isTextField, mergeDefaultValues, mergeSchemas, omitFields, pickFields, section, sectionUntitled, validateSchema };

package/dist/server.mjs

@@ -154,20 +154,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;
+}
+/**
 * Generates react-hook-form `RegisterOptions`-compatible validation rules
 * from a field's schema props. Maps `required`, `min`, `max`, `minLength`,
 * `maxLength`, `pattern`, and `validate` to RHF rules.
@@ -438,12 +639,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. */
@@ -716,4 +918,4 @@ function sectionUntitled(fields, props = {}) {
 }
 
 //#endregion
-export { buildValidationRules, cn, defineField, defineSchema, defineSection, evaluateCondition, extendSection, extractDefaultValues, extractWatchNames, field, flattenSchema, isArrayField, isChoiceField, isConditionalField, isContainerField, isDateField, isDynamicField, isNumericField, isTextField, mergeSchemas, omitFields, pickFields, section, sectionUntitled };
+export { buildFieldDefaults, buildValidationRules, cn, defineField, defineSchema, defineSection, evaluateCondition, extendSection, extractDefaultValues, extractWatchNames, field, flattenSchema, isArrayField, isChoiceField, isConditionalField, isContainerField, isDateField, isDynamicField, isNumericField, isTextField, mergeDefaultValues, mergeSchemas, omitFields, pickFields, section, sectionUntitled, validateSchema };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/formkit",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Headless, type-safe form generation engine for React 19. Schema-driven with full TypeScript support.",
   "author": "Classytic",
   "license": "MIT",
@@ -96,6 +96,7 @@
     "@vitejs/plugin-react": "^5.2.0",
     "clsx": "^2.1.1",
     "eslint": "^9.39.4",
+    "eslint-plugin-react-hooks": "^7.1.1",
     "happy-dom": "^20.9.0",
     "react": "^19.2.6",
     "react-dom": "^19.2.6",