@codeleap/form 7.3.0-next.0 → 7.3.1-next.0

package/dist/fields/index.d.ts

@@ -22,7 +22,7 @@ import { FileField } from "./file";
 export declare const fields: {
     text: <A extends {
         name?: string;
-        defaultValue?: string | null | undefined;
+        defaultValue?: string | (() => string) | (() => Promise<string>) | null | undefined;
         state?: import("nanostores").WritableAtom<string> | undefined;
         validate?: import("./text").TextValidator<any, any> | undefined;
         loader?: ((form: any) => Partial<Omit<import("..").FieldOptions<string, import("./text").TextValidator<any, any>>, "loader">>) | undefined;
@@ -34,7 +34,7 @@ export declare const fields: {
     list: typeof listFieldFactory;
     number: <A extends {
         name?: string;
-        defaultValue?: number | number[] | null | undefined;
+        defaultValue?: number | number[] | (() => number | number[]) | (() => Promise<number | number[]>) | null | undefined;
         state?: import("..").FieldState<number | number[]> | undefined;
         validate?: import("./number").NumberValidator<any, any> | undefined;
         loader?: ((form: any) => Partial<Omit<import("..").FieldOptions<number | number[], import("./number").NumberValidator<any, any>>, "loader">>) | undefined;
@@ -45,7 +45,7 @@ export declare const fields: {
     }>(options?: A | undefined) => import("..").Field<number | number[], A["validate"], A["validate"] extends infer T ? T extends A["validate"] ? T extends import("..").Validator<number | number[], infer R, any> ? R : never : never : never, A["validate"] extends infer T_1 ? T_1 extends A["validate"] ? T_1 extends import("..").Validator<number | number[], any, infer E> ? E : never : never : never>;
     boolean: <A extends {
         name?: string;
-        defaultValue?: boolean | null | undefined;
+        defaultValue?: boolean | (() => boolean) | (() => Promise<boolean>) | null | undefined;
         state?: import("nanostores").WritableAtom<boolean> | undefined;
         validate?: import("./bool").BooleanValidator<any, any> | undefined;
         loader?: ((form: any) => Partial<Omit<import("..").FieldOptions<boolean, import("./bool").BooleanValidator<any, any>>, "loader">>) | undefined;
@@ -53,7 +53,7 @@ export declare const fields: {
     } & import("..").ExtraFieldOptions>(options?: A | undefined) => import("..").Field<boolean, A["validate"], A["validate"] extends infer T ? T extends A["validate"] ? T extends import("..").Validator<boolean, infer R, any> ? R : never : never : never, A["validate"] extends infer T_1 ? T_1 extends A["validate"] ? T_1 extends import("..").Validator<boolean, any, infer E> ? E : never : never : never>;
     selectable: <A extends {
         name?: string;
-        defaultValue?: (string | number) | null | undefined;
+        defaultValue?: (string | number) | (() => string | number) | (() => Promise<string | number>) | null | undefined;
         state?: import("nanostores").WritableAtom<string | number> | undefined;
         validate?: import("./selectable").SelectableValidator<string | number, any, any> | undefined;
         loader?: ((form: any) => Partial<Omit<import("..").FieldOptions<string | number, import("./selectable").SelectableValidator<string | number, any, any>>, "loader">>) | undefined;
@@ -65,7 +65,7 @@ export declare const fields: {
     }>(options?: A | undefined) => import("..").Field<string | number, A["validate"], A["validate"] extends infer T ? T extends A["validate"] ? T extends import("..").Validator<string | number, infer R, any> ? R : never : never : never, A["validate"] extends infer T_1 ? T_1 extends A["validate"] ? T_1 extends import("..").Validator<string | number, any, infer E> ? E : never : never : never>;
     date: <A extends {
         name?: string;
-        defaultValue?: Date | null | undefined;
+        defaultValue?: Date | (() => Date) | (() => Promise<Date>) | null | undefined;
         state?: import("..").FieldState<Date> | undefined;
         validate?: import("./date").DateValidator<any, any> | undefined;
         loader?: ((form: any) => Partial<Omit<import("..").FieldOptions<Date, import("./date").DateValidator<any, any>>, "loader">>) | undefined;

package/dist/fields/list.d.ts

@@ -1,10 +1,10 @@
-import { Field } from "../lib/Field";
-import { FieldOptions, Validator } from "../types";
+import { Field } from '../lib/Field';
+import { FieldOptions, Validator } from '../types';
 /** Validator signature for array-valued fields. `R` and `Err` are the result and error types for the whole list, not individual items. */
 export type ListValidator<Val, R = any, Err = any> = Validator<Val[], R, Err>;
 type ExtractFieldValue<T> = T extends Field<infer Value, any> ? Value : never;
-type AsListValidator<T> = T extends Field<infer Value, infer Validate> ? Validator<Value[], Validate extends Validator<any, infer R, any> ? R[] : never, Validate extends Validator<any, any, infer Err> ? Err[] : never> : never;
-export type _ListFieldOptions<T> = T extends Field<infer Value, infer Validate> ? FieldOptions<Value[], Validator<Value[], Validate extends Validator<any, infer R, any> ? R[] : never, Validate extends Validator<any, any, infer Err> ? Err[] : never>> : never;
+type AsListValidator<T> = T extends Field<infer Value, infer Validate> ? Validator<Value[], Validate extends Validator<any, infer R, any> ? R[] : unknown, Validate extends Validator<any, any, infer Err> ? Err[] : unknown> : never;
+export type _ListFieldOptions<T> = T extends Field<infer Value, infer Validate> ? FieldOptions<Value[], Validator<Value[], Validate extends Validator<any, infer R, any> ? R[] : unknown, Validate extends Validator<any, any, infer Err> ? Err[] : unknown>> : never;
 export type ListFieldOptions<ItemField extends Field<any, any>> = {
     item: ItemField;
 } & _ListFieldOptions<ItemField>;

package/dist/fields/list.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../src/fields/list.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAA;AACpC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAElD,0IAA0I;AAC1I,MAAM,MAAM,aAAa,CAAC,GAAG,EAAE,CAAC,GAAG,GAAG,EAAE,GAAG,GAAG,GAAG,IAAI,SAAS,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,GAAG,CAAC,CAAA;AAE7E,KAAK,iBAAiB,CAAC,CAAC,IAAI,CAAC,SAAS,KAAK,CAAC,MAAM,KAAK,EAAE,GAAG,CAAC,GAAG,KAAK,GAAG,KAAK,CAAA;AAE7E,KAAK,eAAe,CAAC,CAAC,IAAI,CAAC,SAAS,KAAK,CAAC,MAAM,KAAK,EAAE,MAAM,QAAQ,CAAC,GACpE,SAAS,CACP,KAAK,EAAE,EACP,QAAQ,SAAS,SAAS,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,EAAE,GAAG,KAAK,EAC3D,QAAQ,SAAS,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,GAAG,EAAE,GAAG,KAAK,CAChE,GACA,KAAK,CAAA;AAER,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI,CAAC,SAAS,KAAK,CAAC,MAAM,KAAK,EAAE,MAAM,QAAQ,CAAC,GAAG,YAAY,CAC5F,KAAK,EAAE,EACP,SAAS,CACP,KAAK,EAAE,EACP,QAAQ,SAAS,SAAS,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,EAAE,GAAG,KAAK,EAC3D,QAAQ,SAAS,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,GAAG,EAAE,GAAG,KAAK,CAChE,CACF,GAAG,KAAK,CAAA;AAET,MAAM,MAAM,gBAAgB,CAAC,SAAS,SAAS,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI;IAChE,IAAI,EAAE,SAAS,CAAA;CAChB,GAAI,iBAAiB,CAAC,SAAS,CAAC,CAAA;AAEjC;;;;;;;;;GASG;AACH,qBAAa,SAAS,CAAC,CAAC,SAAS,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,CAAE,SAAQ,KAAK,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC;IACzG,KAAK,SAAS;gBAEF,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC;CA+BzC;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,KAAK,CAAC,GAAG,EAAC,GAAG,CAAC,EAAE,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAErG"}
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../src/fields/list.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAA;AACpC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAElD,0IAA0I;AAC1I,MAAM,MAAM,aAAa,CAAC,GAAG,EAAE,CAAC,GAAG,GAAG,EAAE,GAAG,GAAG,GAAG,IAAI,SAAS,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,GAAG,CAAC,CAAA;AAE7E,KAAK,iBAAiB,CAAC,CAAC,IAAI,CAAC,SAAS,KAAK,CAAC,MAAM,KAAK,EAAE,GAAG,CAAC,GAAG,KAAK,GAAG,KAAK,CAAA;AAE7E,KAAK,eAAe,CAAC,CAAC,IAAI,CAAC,SAAS,KAAK,CAAC,MAAM,KAAK,EAAE,MAAM,QAAQ,CAAC,GACpE,SAAS,CACP,KAAK,EAAE,EACP,QAAQ,SAAS,SAAS,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,EAAE,GAAG,OAAO,EAC7D,QAAQ,SAAS,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,GAAG,EAAE,GAAG,OAAO,CAClE,GACA,KAAK,CAAA;AAER,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI,CAAC,SAAS,KAAK,CAAC,MAAM,KAAK,EAAE,MAAM,QAAQ,CAAC,GAAG,YAAY,CAC5F,KAAK,EAAE,EACP,SAAS,CACP,KAAK,EAAE,EACP,QAAQ,SAAS,SAAS,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,EAAE,GAAG,OAAO,EAC7D,QAAQ,SAAS,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,GAAG,EAAE,GAAG,OAAO,CAClE,CACF,GAAG,KAAK,CAAA;AAET,MAAM,MAAM,gBAAgB,CAAC,SAAS,SAAS,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI;IAChE,IAAI,EAAE,SAAS,CAAA;CAChB,GAAG,iBAAiB,CAAC,SAAS,CAAC,CAAA;AAEhC;;;;;;;;;GASG;AACH,qBAAa,SAAS,CAAC,CAAC,SAAS,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,CAAE,SAAQ,KAAK,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC;IACzG,KAAK,SAAS;gBAEF,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC;CAiCzC;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAEtG"}

package/dist/fields/list.js

@@ -1,4 +1,4 @@
-import { Field } from "../lib/Field";
+import { Field } from '../lib/Field';
 /**
  * Field that holds an array of values, each validated by a delegate `item`
  * field. The built-in validator iterates every element through
@@ -10,17 +10,18 @@ import { Field } from "../lib/Field";
  * does not own its own atom. Do not call `use()` on it directly.
  */
 export class ListField extends Field {
-    _type = "LIST";
+    _type = 'LIST';
     constructor(options) {
         super({
             ...options,
             validate: ((v, form) => {
-                if (!options.item?.validate)
+                if (!options.item?.validate) {
                     return {
-                        isValid: true
+                        isValid: true,
                     };
+                }
                 const errors = [];
-                for (const value of v) {
+                for (const value of (v ?? [])) {
                     const validation = options.item?.validate?.(value);
                     if (!validation.isValid) {
                         errors.push(validation);

package/dist/fields/list.js.map

@@ -1 +1 @@
-{"version":3,"file":"list.js","sourceRoot":"","sources":["../../src/fields/list.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAA;AA6BpC;;;;;;;;;GASG;AACH,MAAM,OAAO,SAAqC,SAAQ,KAAiD;IACzG,KAAK,GAAG,MAAM,CAAA;IAEd,YAAY,OAA4B;QACtC,KAAK,CAAC;YACJ,GAAG,OAAO;YACV,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE;gBACrB,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ;oBAAE,OAAO;wBAClC,OAAO,EAAE,IAAI;qBACd,CAAA;gBAED,MAAM,MAAM,GAAG,EAAE,CAAA;gBAEjB,KAAK,MAAM,KAAK,IAAI,CAAC,EAAE,CAAC;oBACtB,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,CAAC,KAAK,CAAC,CAAA;oBAElD,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;wBACxB,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;oBACzB,CAAC;gBACH,CAAC;gBAED,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;oBAClB,OAAO;wBACL,OAAO,EAAE,KAAK;wBACd,KAAK,EAAE,MAAM;qBACd,CAAA;gBACH,CAAC;gBAED,OAAO;oBACL,OAAO,EAAE,IAAI;iBACd,CAAA;YACH,CAAC,CAAuB;SAC8C,CAAC,CAAA;IAC3E,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAA2B,OAA4B;IACrF,OAAO,IAAI,SAAS,CAAC,OAAO,CAAC,CAAA;AAC/B,CAAC"}
+{"version":3,"file":"list.js","sourceRoot":"","sources":["../../src/fields/list.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAA;AA6BpC;;;;;;;;;GASG;AACH,MAAM,OAAO,SAAqC,SAAQ,KAAiD;IACzG,KAAK,GAAG,MAAM,CAAA;IAEd,YAAY,OAA4B;QACtC,KAAK,CAAC;YACJ,GAAG,OAAO;YACV,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE;gBACrB,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,CAAC;oBAC5B,OAAO;wBACL,OAAO,EAAE,IAAI;qBACd,CAAA;gBACH,CAAC;gBAED,MAAM,MAAM,GAAG,EAAE,CAAA;gBAEjB,KAAK,MAAM,KAAK,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;oBAC9B,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,CAAC,KAAK,CAAC,CAAA;oBAElD,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;wBACxB,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;oBACzB,CAAC;gBACH,CAAC;gBAED,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;oBAClB,OAAO;wBACL,OAAO,EAAE,KAAK;wBACd,KAAK,EAAE,MAAM;qBACd,CAAA;gBACH,CAAC;gBAED,OAAO;oBACL,OAAO,EAAE,IAAI;iBACd,CAAA;YACH,CAAC,CAAuB;SAC8C,CAAC,CAAA;IAC3E,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAA4B,OAA4B;IACtF,OAAO,IAAI,SAAS,CAAC,OAAO,CAAC,CAAA;AAC/B,CAAC"}

package/dist/lib/Form.d.ts

@@ -1,4 +1,5 @@
 import { GlobalState } from "@codeleap/store";
+import { DependencyList } from "react";
 import { FieldPaths, FieldTuples, FormDef, FormValues, PropertyForKeys, ValidationResult } from "../types";
 type FormSelector<T extends FormDef, S> = (form: Form<T>) => S;
 /**
@@ -37,9 +38,10 @@ declare class Form<T extends FormDef> {
     slice<K extends FieldPaths<T>>(field: K): import("nanostores").WritableAtom<unknown>;
     iterFields<V>(cb: (field: FieldTuples<T>, index: number) => V): V[];
     /**
-     * Bulk-sets field values from a partial record. Boolean fields require an
-     * explicit `boolean` value; all other fields skip `undefined` and falsy
-     * values. Use `resetValues()` to restore all fields to their initial values.
+     * Bulk-sets field values from a partial record. Only keys present in
+     * `values` are written — absent keys leave the corresponding field
+     * untouched. Falsy values (`''`, `0`, `false`, `null`) are written as-is.
+     * Use `resetValues()` to restore all fields to their initial values.
      */
     setValues(values: Partial<FormValues<T>>): void;
     resetValues(): void;
@@ -65,6 +67,17 @@ declare class Form<T extends FormDef> {
     register(field: FieldPaths<T>): import("..").IFieldProps;
     use<Selected>(selector: FormSelector<T, Selected>): Selected;
     useReset(): void;
+    /**
+     * Initializes form fields from async or derived data at mount time.
+     * Calls `setValues` inside a `useEffect` whenever `values` is non-null and
+     * the deps array changes. Pass `null` or `undefined` to skip (e.g. while a
+     * query is still loading).
+     *
+     * @example
+     * const { data, isSuccess } = useQuery(...)
+     * myForm.useInitialize(isSuccess ? data : null)
+     */
+    useInitialize(values: Partial<FormValues<T>> | null | undefined, deps?: DependencyList): void;
     useShared<Selected>(selector: FormSelector<T, Selected>): Selected;
 }
 /**

package/dist/lib/Form.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Form.d.ts","sourceRoot":"","sources":["../../src/lib/Form.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,WAAW,EAAe,MAAM,iBAAiB,CAAA;AAG5E,OAAO,EAAE,UAAU,EAAuB,WAAW,EAAE,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AAiB/H,KAAK,YAAY,CAAC,CAAC,SAAS,OAAO,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,KAAM,CAAC,CAAA;AAI/D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,cAAM,IAAI,CAAC,CAAC,SAAS,OAAO;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,EAAE,CAAC,CAAA;IACT,KAAK,EAAE,WAAW,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAA;gBAGrB,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAchC,IAAI,MAAM,8HAET;IAED,IAAI,SAAS,YAEZ;IAGD,OAAO;IAQP,IAAI,OAAO,YAIV;IAED,KAAK,CAAC,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;IAgBvC,UAAU,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,CAAC;IAe7D;;;;OAIG;IACH,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAQxC,WAAW;IAMX,WAAW;IAUX;;;;OAIG;IACH,YAAY;;;;IAWZ,QAAQ,CAAC,MAAM,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,GAAG,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,eAAe,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC;IA2BxK;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC;IAO7B,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,YAAY,CAAC,CAAC,EAAE,QAAQ,CAAC,GAAG,QAAQ;IAQ5D,QAAQ;IAKR,SAAS,CAAC,QAAQ,EAAE,QAAQ,EAAE,YAAY,CAAC,CAAC,EAAE,QAAQ,CAAC,GAAG,QAAQ;CAiBnE;AAGD;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,WAO9D;AAED;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,GAAG,SAAS,OAAO,EAAE,GAAG,IAAI,EAAE,qBAAqB,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,aAEzF"}
+{"version":3,"file":"Form.d.ts","sourceRoot":"","sources":["../../src/lib/Form.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,WAAW,EAAe,MAAM,iBAAiB,CAAA;AAE5E,OAAO,EAAE,cAAc,EAAsE,MAAM,OAAO,CAAA;AAC1G,OAAO,EAAE,UAAU,EAAuB,WAAW,EAAE,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AAiB/H,KAAK,YAAY,CAAC,CAAC,SAAS,OAAO,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,KAAM,CAAC,CAAA;AAI/D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,cAAM,IAAI,CAAC,CAAC,SAAS,OAAO;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,EAAE,CAAC,CAAA;IACT,KAAK,EAAE,WAAW,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAA;gBAGrB,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAehC,IAAI,MAAM,8HAET;IAED,IAAI,SAAS,YAEZ;IAGD,OAAO;IAQP,IAAI,OAAO,YAIV;IAED,KAAK,CAAC,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;IAgBvC,UAAU,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,CAAC;IAe7D;;;;;OAKG;IACH,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAQxC,WAAW;IAMX,WAAW;IAUX;;;;OAIG;IACH,YAAY;;;;IAWZ,QAAQ,CAAC,MAAM,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,GAAG,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,eAAe,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC;IA2BxK;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC;IAO7B,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,YAAY,CAAC,CAAC,EAAE,QAAQ,CAAC,GAAG,QAAQ;IAQ5D,QAAQ;IAMR;;;;;;;;;OASG;IACH,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,IAAI,CAAC,EAAE,cAAc;IAMtF,SAAS,CAAC,QAAQ,EAAE,QAAQ,EAAE,YAAY,CAAC,CAAC,EAAE,QAAQ,CAAC,GAAG,QAAQ;CAiBnE;AAGD;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,WAO9D;AAED;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,GAAG,SAAS,OAAO,EAAE,GAAG,IAAI,EAAE,qBAAqB,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,aAEzF"}

package/dist/lib/Form.js

@@ -45,6 +45,7 @@ class Form {
         this.use = this.use.bind(this);
         this.useShared = this.useShared.bind(this);
         this.useReset = this.useReset.bind(this);
+        this.useInitialize = this.useInitialize.bind(this);
     }
     get values() {
         return this.state.get();
@@ -82,17 +83,17 @@ class Form {
         return results;
     }
     /**
-     * Bulk-sets field values from a partial record. Boolean fields require an
-     * explicit `boolean` value; all other fields skip `undefined` and falsy
-     * values. Use `resetValues()` to restore all fields to their initial values.
+     * Bulk-sets field values from a partial record. Only keys present in
+     * `values` are written — absent keys leave the corresponding field
+     * untouched. Falsy values (`''`, `0`, `false`, `null`) are written as-is.
+     * Use `resetValues()` to restore all fields to their initial values.
      */
     setValues(values) {
+        const source = values ?? {};
         this.iterFields(([name, field]) => {
-            const value = values?.[name];
-            if (field._type === 'BOOLEAN' && TypeGuards.isBoolean(value))
-                field.setValue(value);
-            else if (value)
-                field.setValue(value);
+            if (!(name in source))
+                return;
+            field.setValue(source[name]);
         });
     }
     resetValues() {
@@ -158,6 +159,22 @@ class Form {
             this.resetValues();
         });
     }
+    /**
+     * Initializes form fields from async or derived data at mount time.
+     * Calls `setValues` inside a `useEffect` whenever `values` is non-null and
+     * the deps array changes. Pass `null` or `undefined` to skip (e.g. while a
+     * query is still loading).
+     *
+     * @example
+     * const { data, isSuccess } = useQuery(...)
+     * myForm.useInitialize(isSuccess ? data : null)
+     */
+    useInitialize(values, deps) {
+        useEffect(() => {
+            if (!TypeGuards.isNil(values))
+                this.setValues(values);
+        }, deps ?? [values]);
+    }
     useShared(selector) {
         const [selected, setSelected] = useState(() => selector(this));
         const reselect = useCallback(() => {

package/dist/lib/Form.js.map

@@ -1 +1 @@
-{"version":3,"file":"Form.js","sourceRoot":"","sources":["../../src/lib/Form.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Form.js","sourceRoot":"","sources":["../../src/lib/Form.ts"],"names":[],"mappings":"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"}

package/dist/types/field.d.ts

@@ -5,7 +5,7 @@ export interface ExtraFieldOptions {
 }
 export type FieldOptions<T, Validate extends Validator<T, any, any>> = {
     name?: string;
-    defaultValue?: T | null;
+    defaultValue?: T | null | (() => T) | (() => Promise<T>);
     state?: FieldState<T>;
     validate?: Validate;
     loader?: (form: any) => Partial<Omit<FieldOptions<T, Validate>, 'loader'>>;

package/dist/types/field.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"field.d.ts","sourceRoot":"","sources":["../../src/types/field.ts"],"names":[],"mappings":"AAAA,OAAO,EAAG,aAAa,EAAE,MAAM,YAAY,CAAA;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAIxC,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC,CAAA;AAE5C,MAAM,WAAW,iBAAiB;CAEjC;AAED,MAAM,MAAM,YAAY,CACtB,CAAC,EACD,QAAQ,SAAS,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,IACrC;IACF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,YAAY,CAAC,EAAE,CAAC,GAAG,IAAI,CAAA;IACvB,KAAK,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,CAAA;IAErB,QAAQ,CAAC,EAAE,QAAQ,CAAA;IAEnB,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,CAC7B,IAAI,CAAC,YAAY,CAAC,CAAC,EAAE,QAAQ,CAAE,EAAE,QAAQ,CAAC,CAC3C,CAAA;IAED,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,IAAI,CAAA;CAEtC,GAAG,iBAAiB,CAAA;AAGrB,MAAM,MAAM,kBAAkB,GAAG;IAC/B,CAAC,CAAC,EAAE,MAAM,CAAA;IACV,CAAC,CAAC,EAAE,MAAM,CAAA;IACV,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA"}
+{"version":3,"file":"field.d.ts","sourceRoot":"","sources":["../../src/types/field.ts"],"names":[],"mappings":"AAAA,OAAO,EAAG,aAAa,EAAE,MAAM,YAAY,CAAA;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAIxC,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC,CAAA;AAE5C,MAAM,WAAW,iBAAiB;CAEjC;AAED,MAAM,MAAM,YAAY,CACtB,CAAC,EACD,QAAQ,SAAS,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,IACrC;IACF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,YAAY,CAAC,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC,CAAA;IACxD,KAAK,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,CAAA;IAErB,QAAQ,CAAC,EAAE,QAAQ,CAAA;IAEnB,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,CAC7B,IAAI,CAAC,YAAY,CAAC,CAAC,EAAE,QAAQ,CAAE,EAAE,QAAQ,CAAC,CAC3C,CAAA;IAED,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,IAAI,CAAA;CAEtC,GAAG,iBAAiB,CAAA;AAGrB,MAAM,MAAM,kBAAkB,GAAG;IAC/B,CAAC,CAAC,EAAE,MAAM,CAAA;IACV,CAAC,CAAC,EAAE,MAAM,CAAA;IACV,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA"}

package/dist/types/globals.d.ts

@@ -10,6 +10,8 @@ export interface IFieldRef<T> {
     emit(event: string, ...args: any[]): void;
 }
 export interface IFieldProps {
+    name?: string;
+    field: any;
 }
 export type PropTransformer = (props: AnyRecord) => AnyRecord;
 //# sourceMappingURL=globals.d.ts.map

package/dist/types/globals.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"globals.d.ts","sourceRoot":"","sources":["../../src/types/globals.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAE3C,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,QAAQ,IAAI,CAAC,CAAA;IACb,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/B,KAAK,IAAI,IAAI,CAAA;IACb,IAAI,IAAI,IAAI,CAAA;IACZ,WAAW,IAAI,IAAI,CAAA;IACnB,qBAAqB,IAAI,IAAI,CAAA;IAC7B,SAAS,IAAI,IAAI,CAAA;IACjB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAA;CAC1C;AAGD,MAAM,WAAW,WAAW;CAE3B;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,SAAS,KAAK,SAAS,CAAA"}
+{"version":3,"file":"globals.d.ts","sourceRoot":"","sources":["../../src/types/globals.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAE3C,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,QAAQ,IAAI,CAAC,CAAA;IACb,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/B,KAAK,IAAI,IAAI,CAAA;IACb,IAAI,IAAI,IAAI,CAAA;IACZ,WAAW,IAAI,IAAI,CAAA;IACnB,qBAAqB,IAAI,IAAI,CAAA;IAC7B,SAAS,IAAI,IAAI,CAAA;IACjB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAA;CAC1C;AAGD,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,GAAG,CAAA;CACX;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,SAAS,KAAK,SAAS,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codeleap/form",
-  "version": "7.3.0-next.0",
+  "version": "7.3.1-next.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -22,10 +22,10 @@
     "directory": "packages/form"
   },
   "devDependencies": {
-    "@codeleap/config": "7.3.0-next.0",
-    "@codeleap/types": "7.3.0-next.0",
-    "@codeleap/store": "7.3.0-next.0",
-    "@codeleap/hooks": "7.3.0-next.0",
+    "@codeleap/config": "7.3.1-next.0",
+    "@codeleap/types": "7.3.1-next.0",
+    "@codeleap/store": "7.3.1-next.0",
+    "@codeleap/hooks": "7.3.1-next.0",
     "zod": "4.4.3",
     "ts-node-dev": "1.1.8"
   },
@@ -35,10 +35,10 @@
     "playground": "bun src/test.ts"
   },
   "peerDependencies": {
-    "@codeleap/types": "7.3.0-next.0",
-    "@codeleap/store": "7.3.0-next.0",
-    "@codeleap/logger": "7.3.0-next.0",
-    "@codeleap/hooks": "7.3.0-next.0",
+    "@codeleap/types": "7.3.1-next.0",
+    "@codeleap/store": "7.3.1-next.0",
+    "@codeleap/logger": "7.3.1-next.0",
+    "@codeleap/hooks": "7.3.1-next.0",
     "zod": "*",
     "react": "19.1.0",
     "typescript": "5.5.2"

package/src/fields/list.ts

@@ -1,31 +1,31 @@
-import { Field } from "../lib/Field"
-import { FieldOptions, Validator } from "../types"
+import { Field } from '../lib/Field'
+import { FieldOptions, Validator } from '../types'
 
 /** Validator signature for array-valued fields. `R` and `Err` are the result and error types for the whole list, not individual items. */
 export type ListValidator<Val, R = any, Err = any> = Validator<Val[], R, Err>
 
 type ExtractFieldValue<T> = T extends Field<infer Value, any> ? Value : never
 
-type AsListValidator<T> = T extends Field<infer Value, infer Validate> ?  
+type AsListValidator<T> = T extends Field<infer Value, infer Validate> ?
   Validator<
-    Value[], 
-    Validate extends Validator<any, infer R, any> ? R[] : never, 
-    Validate extends Validator<any, any, infer Err> ? Err[] : never
+    Value[],
+    Validate extends Validator<any, infer R, any> ? R[] : unknown,
+    Validate extends Validator<any, any, infer Err> ? Err[] : unknown
   >
  : never
 
 export type _ListFieldOptions<T> = T extends Field<infer Value, infer Validate> ? FieldOptions<
   Value[],
   Validator<
-    Value[], 
-    Validate extends Validator<any, infer R, any> ? R[] : never, 
-    Validate extends Validator<any, any, infer Err> ? Err[] : never
+    Value[],
+    Validate extends Validator<any, infer R, any> ? R[] : unknown,
+    Validate extends Validator<any, any, infer Err> ? Err[] : unknown
   >
 > : never
 
 export type ListFieldOptions<ItemField extends Field<any, any>> = {
   item: ItemField
-}  & _ListFieldOptions<ItemField>
+} & _ListFieldOptions<ItemField>
 
 /**
  * Field that holds an array of values, each validated by a delegate `item`
@@ -38,19 +38,21 @@ export type ListFieldOptions<ItemField extends Field<any, any>> = {
  * does not own its own atom. Do not call `use()` on it directly.
  */
 export class ListField<T extends Field<any, any>> extends Field<ExtractFieldValue<T>[], AsListValidator<T>> {
-  _type = "LIST"
+  _type = 'LIST'
 
   constructor(options: ListFieldOptions<T>) {
     super({
       ...options,
       validate: ((v, form) => {
-        if (!options.item?.validate) return {
-          isValid: true
+        if (!options.item?.validate) {
+          return {
+            isValid: true,
+          }
         }
 
         const errors = []
 
-        for (const value of v) {
+        for (const value of (v ?? [])) {
           const validation = options.item?.validate?.(value)
 
           if (!validation.isValid) {
@@ -80,6 +82,6 @@ export class ListField<T extends Field<any, any>> extends Field<ExtractFieldValu
  * exists to provide a consistent `fields.list(...)` call signature alongside
  * the other entries in the `fields` namespace.
  */
-export function listFieldFactory<T extends Field<any,any>>(options: ListFieldOptions<T>): ListField<T> {
+export function listFieldFactory<T extends Field<any, any>>(options: ListFieldOptions<T>): ListField<T> {
   return new ListField(options)
-} 
+}

package/src/lib/Form.ts

@@ -64,6 +64,7 @@ class Form<T extends FormDef> {
     this.use = this.use.bind(this)
     this.useShared = this.useShared.bind(this)
     this.useReset = this.useReset.bind(this)
+    this.useInitialize = this.useInitialize.bind(this)
   }
 
   get values(){
@@ -121,15 +122,16 @@ class Form<T extends FormDef> {
   }
 
   /**
-   * Bulk-sets field values from a partial record. Boolean fields require an
-   * explicit `boolean` value; all other fields skip `undefined` and falsy
-   * values. Use `resetValues()` to restore all fields to their initial values.
+   * Bulk-sets field values from a partial record. Only keys present in
+   * `values` are written — absent keys leave the corresponding field
+   * untouched. Falsy values (`''`, `0`, `false`, `null`) are written as-is.
+   * Use `resetValues()` to restore all fields to their initial values.
    */
   setValues(values: Partial<FormValues<T>>) {
+    const source = values ?? {}
     this.iterFields(([name, field]) => {
-      const value = values?.[name]
-      if (field._type === 'BOOLEAN' && TypeGuards.isBoolean(value)) field.setValue(value)
-      else if (value) field.setValue(value)
+      if (!(name in source)) return
+      field.setValue(source[name] as any)
     })
   }
 
@@ -217,6 +219,23 @@ class Form<T extends FormDef> {
       this.resetValues()
      })
   }
+
+  /**
+   * Initializes form fields from async or derived data at mount time.
+   * Calls `setValues` inside a `useEffect` whenever `values` is non-null and
+   * the deps array changes. Pass `null` or `undefined` to skip (e.g. while a
+   * query is still loading).
+   *
+   * @example
+   * const { data, isSuccess } = useQuery(...)
+   * myForm.useInitialize(isSuccess ? data : null)
+   */
+  useInitialize(values: Partial<FormValues<T>> | null | undefined, deps?: DependencyList) {
+    useEffect(() => {
+      if (!TypeGuards.isNil(values)) this.setValues(values)
+    }, deps ?? [values])
+  }
+
   useShared<Selected>(selector: FormSelector<T, Selected>): Selected {
     const [selected, setSelected] = useState(() => selector(this))
     

package/src/tests/Field.spec.ts

@@ -0,0 +1,186 @@
+import { describe, it, expect, afterEach } from 'bun:test'
+import { Field, ValidationError } from '../lib/Field'
+import { fields } from '../fields'
+import { z } from 'zod'
+import { zodValidator } from '../validators'
+import './setup'
+
+afterEach(() => {
+  Field.transformers.clear()
+})
+
+describe('Field construction', () => {
+  it('initializes with static defaultValue', () => {
+    const field = fields.text({ defaultValue: 'hello' })
+    expect(field.value).toBe('hello')
+  })
+
+  it('initializes with function defaultValue', () => {
+    const field = fields.text({ defaultValue: () => 'from fn' })
+    expect(field.value).toBe('from fn')
+  })
+
+  it('initializes with undefined when no defaultValue', () => {
+    const field = fields.text({})
+    expect(field.value).toBeUndefined()
+  })
+
+  it('errorRevealed starts as false', () => {
+    const field = fields.text({ defaultValue: '' })
+    expect(field.isErrorRevealed).toBe(false)
+  })
+})
+
+describe('Field.setValue', () => {
+  it('updates the stored value', () => {
+    const field = fields.text({ defaultValue: '' })
+    field.setValue('updated')
+    expect(field.value).toBe('updated')
+  })
+
+  it('calls onValueChange callback', () => {
+    const calls: string[] = []
+    const field = fields.text({
+      defaultValue: '',
+      onValueChange: (v) => calls.push(v),
+    })
+    field.setValue('hello')
+    expect(calls).toEqual(['hello'])
+  })
+})
+
+describe('Field.resetValue', () => {
+  it('restores the initial value', () => {
+    const field = fields.text({ defaultValue: 'initial' })
+    field.setValue('changed')
+    field.resetValue()
+    expect(field.value).toBe('initial')
+  })
+
+  it('hides the revealed error', () => {
+    const field = fields.text({ defaultValue: '' })
+    field.revealError()
+    field.resetValue()
+    expect(field.isErrorRevealed).toBe(false)
+  })
+})
+
+describe('Field.changed', () => {
+  it('returns false when value equals initial', () => {
+    const field = fields.text({ defaultValue: 'init' })
+    expect(field.changed()).toBe(false)
+  })
+
+  it('returns true after setValue with a different value', () => {
+    const field = fields.text({ defaultValue: 'init' })
+    field.setValue('different')
+    expect(field.changed()).toBe(true)
+  })
+
+  it('returns false after resetValue', () => {
+    const field = fields.text({ defaultValue: 'init' })
+    field.setValue('different')
+    field.resetValue()
+    expect(field.changed()).toBe(false)
+  })
+})
+
+describe('Field.validate', () => {
+  it('returns isValid: true for a passing validator', () => {
+    const field = fields.text({
+      defaultValue: 'hello',
+      validate: zodValidator(z.string().min(1)),
+    })
+    expect(field.validate().isValid).toBe(true)
+  })
+
+  it('returns isValid: false for a failing validator', () => {
+    const field = fields.text({
+      defaultValue: '',
+      validate: zodValidator(z.string().min(1, 'Required')),
+    })
+    expect(field.validate().isValid).toBe(false)
+  })
+
+  it('validates the supplied value, not the stored value', () => {
+    const field = fields.text({
+      defaultValue: 'valid',
+      validate: zodValidator(z.string().min(1)),
+    })
+    expect(field.validate('').isValid).toBe(false)
+  })
+
+  it('catches ValidationError and returns structured failure', () => {
+    const field = fields.text({
+      defaultValue: 'x',
+      validate: () => { throw new ValidationError('custom-error') },
+    })
+    const result = field.validate()
+    expect(result.isValid).toBe(false)
+    expect(result.error).toBe('custom-error')
+  })
+
+  it('re-throws non-ValidationError exceptions', () => {
+    const field = fields.text({
+      defaultValue: 'x',
+      validate: () => { throw new Error('unexpected') },
+    })
+    expect(() => field.validate()).toThrow('unexpected')
+  })
+})
+
+describe('Field.isValid', () => {
+  it('is true when validator passes', () => {
+    const field = fields.text({ defaultValue: 'hello', validate: zodValidator(z.string().min(1)) })
+    expect(field.isValid).toBe(true)
+  })
+
+  it('is false when validator fails', () => {
+    const field = fields.text({ defaultValue: '', validate: zodValidator(z.string().min(1)) })
+    expect(field.isValid).toBe(false)
+  })
+})
+
+describe('Field error visibility', () => {
+  it('revealError sets isErrorRevealed to true', () => {
+    const field = fields.text({ defaultValue: '' })
+    field.revealError()
+    expect(field.isErrorRevealed).toBe(true)
+  })
+
+  it('hideError sets isErrorRevealed to false', () => {
+    const field = fields.text({ defaultValue: '' })
+    field.revealError()
+    field.hideError()
+    expect(field.isErrorRevealed).toBe(false)
+  })
+})
+
+describe('Field.props and transformers', () => {
+  it('props returns field name and field reference', () => {
+    const field = fields.text({ defaultValue: '', name: 'email' })
+    const props = field.props()
+    expect(props.name).toBe('email')
+    expect(props.field).toBe(field)
+  })
+
+  it('attachTransformer applies transformation to props', () => {
+    Field.attachTransformer('add-flag', (p) => ({ ...p, flagged: true }))
+    const field = fields.text({ defaultValue: '', name: 'x' })
+    expect((field.props() as any).flagged).toBe(true)
+  })
+
+  it('detachTransformer removes the transformation', () => {
+    Field.attachTransformer('to-remove', (p) => ({ ...p, extra: 1 }))
+    Field.detachTransformer('to-remove')
+    const field = fields.text({ defaultValue: '', name: 'x' })
+    expect((field.props() as any).extra).toBeUndefined()
+  })
+
+  it('multiple transformers compose in insertion order', () => {
+    Field.attachTransformer('first', (p) => ({ ...p, order: 'first' }))
+    Field.attachTransformer('second', (p) => ({ ...p, order: 'second' }))
+    const field = fields.text({ defaultValue: '' })
+    expect((field.props() as any).order).toBe('second')
+  })
+})

package/src/tests/Form.spec.ts

@@ -0,0 +1,160 @@
+import { describe, it, expect } from 'bun:test'
+import { form } from '../lib/Form'
+import { fields } from '../fields'
+import { z } from 'zod'
+import { zodValidator } from '../validators'
+import './setup'
+
+const makeBasicForm = () =>
+  form('basic', {
+    name: fields.text({ defaultValue: 'Alice' }),
+    age: fields.number({ defaultValue: 25 }),
+  })
+
+const makeValidationForm = () =>
+  form('validation', {
+    email: fields.text({ validate: zodValidator(z.string().email('Invalid email')) }),
+    bio: fields.text({ defaultValue: 'hello', validate: zodValidator(z.string().min(1)) }),
+  })
+
+describe('Form construction', () => {
+  it('sets field names from object keys', () => {
+    const f = makeBasicForm()
+    expect(f.fields.name.name).toBe('name')
+    expect(f.fields.age.name).toBe('age')
+  })
+
+  it('initializes values from field defaults', () => {
+    const f = makeBasicForm()
+    expect(f.values.name).toBe('Alice')
+    expect(f.values.age).toBe(25)
+  })
+})
+
+describe('Form.setValues', () => {
+  it('updates only keys present in source', () => {
+    const f = makeBasicForm()
+    f.setValues({ name: 'Bob' })
+    expect(f.values.name).toBe('Bob')
+    expect(f.values.age).toBe(25)
+  })
+
+  it('writes falsy string value', () => {
+    const f = makeBasicForm()
+    f.setValues({ name: '' })
+    expect(f.values.name).toBe('')
+  })
+
+  it('writes zero', () => {
+    const f = makeBasicForm()
+    f.setValues({ age: 0 })
+    expect(f.values.age).toBe(0)
+  })
+})
+
+describe('Form.resetValues', () => {
+  it('restores all fields to initial values', () => {
+    const f = makeBasicForm()
+    f.setValues({ name: 'Bob', age: 30 })
+    f.resetValues()
+    expect(f.values.name).toBe('Alice')
+    expect(f.values.age).toBe(25)
+  })
+
+  it('hides revealed errors', () => {
+    const f = makeValidationForm()
+    f.fields.email.revealError()
+    f.resetValues()
+    expect(f.fields.email.isErrorRevealed).toBe(false)
+  })
+})
+
+describe('Form.changed / isChanged', () => {
+  it('is false when no fields have changed', () => {
+    const f = makeBasicForm()
+    expect(f.changed()).toBe(false)
+    expect(f.isChanged).toBe(false)
+  })
+
+  it('is true when any field changes', () => {
+    const f = makeBasicForm()
+    f.fields.name.setValue('Bob')
+    expect(f.changed()).toBe(true)
+  })
+
+  it('is false after resetValues', () => {
+    const f = makeBasicForm()
+    f.setValues({ name: 'Bob' })
+    f.resetValues()
+    expect(f.changed()).toBe(false)
+  })
+})
+
+describe('Form.isValid', () => {
+  it('is true when all fields pass validation', () => {
+    const f = form('all-valid', {
+      name: fields.text({ defaultValue: 'Alice', validate: zodValidator(z.string().min(1)) }),
+    })
+    expect(f.isValid).toBe(true)
+  })
+
+  it('is false when any field fails validation', () => {
+    const f = makeValidationForm()
+    // email starts as undefined → fails z.string().email()
+    expect(f.isValid).toBe(false)
+  })
+})
+
+describe('Form.validate', () => {
+  it('returns a result map keyed by field name', () => {
+    const f = makeValidationForm()
+    const results = f.validate()
+    expect('email' in results).toBe(true)
+    expect('bio' in results).toBe(true)
+  })
+
+  it('reveals errors on all fields when revealErrors is true', () => {
+    const f = makeValidationForm()
+    expect(f.fields.email.isErrorRevealed).toBe(false)
+    f.validate({ revealErrors: true })
+    expect(f.fields.email.isErrorRevealed).toBe(true)
+    expect(f.fields.bio.isErrorRevealed).toBe(true)
+  })
+
+  it('validates only specified fields when fields option is provided', () => {
+    const f = makeValidationForm()
+    const results = f.validate({ fields: ['email'] })
+    expect('email' in results).toBe(true)
+    expect('bio' in results).toBe(false)
+  })
+})
+
+describe('Form.firstInvalid', () => {
+  it('returns undefined when all fields are valid', () => {
+    const f = form('all-valid', {
+      name: fields.text({ defaultValue: 'Alice', validate: zodValidator(z.string().min(1)) }),
+    })
+    expect(f.firstInvalid()).toBeUndefined()
+  })
+
+  it('returns the first invalid field with its validation result', () => {
+    const f = makeValidationForm()
+    const result = f.firstInvalid()
+    expect(result).toBeDefined()
+    expect(result!.validation.isValid).toBe(false)
+    expect(result!.field).toBe(f.fields.email)
+  })
+})
+
+describe('Form.register', () => {
+  it('returns props for a known field', () => {
+    const f = makeBasicForm()
+    const props = f.register('name')
+    expect(props.field).toBe(f.fields.name)
+  })
+
+  it('throws for an unknown field key', () => {
+    const f = makeBasicForm()
+    expect(() => f.register('nonexistent' as any)).toThrow()
+  })
+})

package/src/tests/fields.spec.ts

@@ -0,0 +1,90 @@
+import { describe, it, expect } from 'bun:test'
+import { fields } from '../fields'
+import { z } from 'zod'
+import { zodValidator } from '../validators'
+import './setup'
+
+describe('TextField', () => {
+  it('is valid for any non-empty string by default', () => {
+    const f = fields.text({ defaultValue: 'hello' })
+    expect(f.isValid).toBe(true)
+  })
+
+  it('is valid for undefined by default (z.string().optional())', () => {
+    const f = fields.text({})
+    expect(f.isValid).toBe(true)
+  })
+
+  it('fails with a custom validator', () => {
+    const f = fields.text({
+      defaultValue: 'not-an-email',
+      validate: zodValidator(z.string().email()),
+    })
+    expect(f.isValid).toBe(false)
+  })
+
+  it('has _type TEXT', () => {
+    expect(fields.text({})._type).toBe('TEXT')
+  })
+})
+
+describe('NumberField', () => {
+  it('is valid for a number within default range', () => {
+    const f = fields.number({ defaultValue: 100 })
+    expect(f.isValid).toBe(true)
+  })
+
+  it('is invalid when value is below min', () => {
+    const f = fields.number({ defaultValue: -1, min: 0 })
+    expect(f.isValid).toBe(false)
+  })
+
+  it('is invalid when value exceeds max', () => {
+    const f = fields.number({ defaultValue: 100, max: 50 })
+    expect(f.isValid).toBe(false)
+  })
+
+  it('supports array (range) defaultValue', () => {
+    const f = fields.number({ defaultValue: [10, 90] })
+    expect(f.isValid).toBe(true)
+  })
+
+  it('array range is invalid when any element is out of bounds', () => {
+    const f = fields.number({ defaultValue: [-1, 90], min: 0 })
+    expect(f.isValid).toBe(false)
+  })
+
+  it('has _type NUMBER', () => {
+    expect(fields.number({ defaultValue: 0 })._type).toBe('NUMBER')
+  })
+})
+
+describe('ListField', () => {
+  const makeItemField = () => fields.text({ validate: zodValidator(z.string().min(1)) })
+
+  it('is valid when empty', () => {
+    const f = fields.list({ item: makeItemField(), defaultValue: [] })
+    expect(f.isValid).toBe(true)
+  })
+
+  it('is valid when all items pass item validator', () => {
+    const f = fields.list({ item: makeItemField(), defaultValue: ['a', 'b', 'c'] })
+    expect(f.isValid).toBe(true)
+  })
+
+  it('is invalid when any item fails item validator', () => {
+    const f = fields.list({ item: makeItemField(), defaultValue: ['a', '', 'c'] })
+    expect(f.isValid).toBe(false)
+  })
+
+  it('is always valid when item has no validator', () => {
+    const noValidatorItem = fields.text({})
+    const f = fields.list({ item: noValidatorItem, defaultValue: ['', ''] })
+    expect(f.isValid).toBe(true)
+  })
+
+  it('has _type LIST', () => {
+    const f = fields.list({ item: fields.text({}), defaultValue: [] })
+    expect(f._type).toBe('LIST')
+  })
+})

package/src/tests/hooks.spec.tsx

@@ -0,0 +1,111 @@
+import { describe, it, expect } from 'bun:test'
+import { renderHook, act, waitFor } from '@testing-library/react'
+import { useForm, form } from '../lib/Form'
+import { fields } from '../fields'
+import { z } from 'zod'
+import { zodValidator } from '../validators'
+import './setup'
+
+describe('useForm', () => {
+  it('creates a form with the given id', () => {
+    const { result } = renderHook(() =>
+      useForm('my-form', { name: fields.text({ defaultValue: 'Alice' }) })
+    )
+    expect(result.current.id).toBe('my-form')
+  })
+
+  it('returns a stable reference across re-renders', () => {
+    const { result, rerender } = renderHook(() =>
+      useForm('stable', { name: fields.text({ defaultValue: '' }) })
+    )
+    const first = result.current
+    rerender()
+    expect(result.current).toBe(first)
+  })
+
+  it('sets field names from the definition keys', () => {
+    const { result } = renderHook(() =>
+      useForm('named', {
+        email: fields.text({}),
+        password: fields.text({}),
+      })
+    )
+    expect(result.current.fields.email.name).toBe('email')
+    expect(result.current.fields.password.name).toBe('password')
+  })
+})
+
+describe('Form.useInitialize', () => {
+  it('does not change values when called with null', () => {
+    const f = form('init-null', { name: fields.text({ defaultValue: 'original' }) })
+    renderHook(() => { f.useInitialize(null) })
+    expect(f.values.name).toBe('original')
+  })
+
+  it('does not change values when called with undefined', () => {
+    const f = form('init-undef', { name: fields.text({ defaultValue: 'original' }) })
+    renderHook(() => { f.useInitialize(undefined) })
+    expect(f.values.name).toBe('original')
+  })
+
+  it('sets values when non-null data is provided', async () => {
+    const f = form('init-values', { name: fields.text({ defaultValue: '' }) })
+    const initValues = { name: 'Bob' }
+    renderHook(() => { f.useInitialize(initValues) })
+    await waitFor(() => {
+      expect(f.values.name).toBe('Bob')
+    })
+  })
+
+  it('re-applies values when deps change', async () => {
+    const f = form('init-deps', { name: fields.text({ defaultValue: '' }) })
+    let trigger = 0
+    const { rerender } = renderHook(() => {
+      f.useInitialize({ name: `value-${trigger}` }, [trigger])
+    })
+    await waitFor(() => { expect(f.values.name).toBe('value-0') })
+
+    trigger = 1
+    rerender()
+    await waitFor(() => { expect(f.values.name).toBe('value-1') })
+  })
+})
+
+describe('Form.useShared', () => {
+  it('returns the initial selected value', () => {
+    const f = form('shared-init', { count: fields.number({ defaultValue: 5 }) })
+    const { result } = renderHook(() => f.useShared((frm) => frm.values.count))
+    expect(result.current).toBe(5)
+  })
+
+  it('updates when the underlying state changes', async () => {
+    const f = form('shared-update', { count: fields.number({ defaultValue: 0 }) })
+    const { result } = renderHook(() => f.useShared((frm) => frm.values.count))
+    expect(result.current).toBe(0)
+
+    act(() => { f.fields.count.setValue(42) })
+
+    await waitFor(() => { expect(result.current).toBe(42) })
+  })
+
+  it('does not reset on unmount', () => {
+    const f = form('shared-no-reset', { name: fields.text({ defaultValue: 'init' }) })
+    f.fields.name.setValue('changed')
+    const { unmount } = renderHook(() => f.useShared((frm) => frm.values.name))
+    unmount()
+    expect(f.values.name).toBe('changed')
+  })
+})
+
+describe('Form.use (resets on unmount)', () => {
+  it('resets all field values when the component unmounts', () => {
+    const f = form('use-reset', { name: fields.text({ defaultValue: 'initial' }) })
+    f.fields.name.setValue('changed')
+
+    const { unmount } = renderHook(() => f.use((frm) => frm.values.name))
+    expect(f.values.name).toBe('changed')
+
+    unmount()
+    expect(f.values.name).toBe('initial')
+  })
+})

package/src/tests/setup.ts

@@ -0,0 +1,25 @@
+import { afterEach } from 'bun:test'
+import { cleanup } from '@testing-library/react'
+import { z } from 'zod'
+import { zodValidator } from '../validators'
+import { fields } from '../fields'
+import { form } from '../lib/Form'
+
+export const makeTextField = (defaultValue = '') =>
+  fields.text({ defaultValue })
+
+export const makeRequiredTextField = () =>
+  fields.text({
+    defaultValue: '',
+    validate: zodValidator(z.string().min(1, 'Required')),
+  })
+
+export const makeLoginForm = () =>
+  form('login', {
+    email: fields.text({ validate: zodValidator(z.string().email('Invalid email')) }),
+    password: fields.text({ validate: zodValidator(z.string().min(8, 'Too short')) }),
+  })
+
+afterEach(() => {
+  cleanup()
+})

package/src/types/field.ts

@@ -14,7 +14,7 @@ export type FieldOptions<
   Validate extends Validator<T, any, any>
 > = {
   name?: string
-  defaultValue?: T | null
+  defaultValue?: T | null | (() => T) | (() => Promise<T>)
   state?: FieldState<T>
   
   validate?: Validate

package/src/types/globals.ts

@@ -13,7 +13,8 @@ export interface IFieldRef<T> {
 
 
 export interface IFieldProps {
-
+  name?: string
+  field: any
 }
 
 export type PropTransformer = (props: AnyRecord) => AnyRecord