@codeleap/form 6.3.0 → 6.8.0

package/dist/lib/Form.d.ts

@@ -0,0 +1,88 @@
+import { GlobalState } from "@codeleap/store";
+import { FieldPaths, FieldTuples, FormDef, FormValues, PropertyForKeys, ValidationResult } from "../types";
+type FormSelector<T extends FormDef, S> = (form: Form<T>) => S;
+/**
+ * Container that owns the shared nanostores `GlobalState` atom for a group of
+ * fields and wires each field's individual atom to a slice of that shared
+ * state. This ensures a single source of truth: reading `form.values` always
+ * reflects the live atom values of every field.
+ *
+ * **Initialization order**
+ * The constructor calls `attachState()` synchronously, which replaces each
+ * field's own atom with a derived slice and sets the field's `name` from its
+ * object key in the shape. Fields must therefore be fully constructed before
+ * being passed to `Form`.
+ *
+ * **React usage**
+ * - `use(selector)` — mounts the form in a component, subscribes to state
+ *   changes via `selector`, and resets all field values on unmount. Prefer
+ *   this for full-page forms.
+ * - `useShared(selector)` — subscribes without the unmount-reset side-effect.
+ *   Use when the form outlives the component (e.g. a global singleton).
+ *
+ * **Validation**
+ * `validate()` runs every field's synchronous validator and returns a map of
+ * results keyed by field name. Pass `revealErrors: true` to simultaneously
+ * flip `errorRevealed` on every field, triggering error display in the UI.
+ */
+declare class Form<T extends FormDef> {
+    id: string;
+    fields: T;
+    state: GlobalState<FormValues<T>>;
+    constructor(id: string, shape: T);
+    get values(): FormValues<T> extends infer T_1 ? T_1 extends FormValues<T> ? T_1 extends undefined ? FormValues<T> : T_1 : never : never;
+    get isChanged(): boolean;
+    changed(): boolean;
+    get isValid(): boolean;
+    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.
+     */
+    setValues(values: Partial<FormValues<T>>): void;
+    resetValues(): void;
+    attachState(): void;
+    /**
+     * Returns the first field (in definition order) that fails validation, along
+     * with its `ValidationResult`. Returns `undefined` when all fields are
+     * valid. Useful for scrolling to the first error on submit.
+     */
+    firstInvalid(): {
+        field: import("./Field").Field<any, any, unknown, unknown>;
+        validation: ValidationResult<unknown, unknown>;
+    } | undefined;
+    validate<Fields extends FieldPaths<T>[] = FieldPaths<T>[]>(options?: {
+        fields?: Fields;
+        revealErrors?: boolean;
+    }): PropertyForKeys<T, Fields[number], '__validationRes'>;
+    /**
+     * Returns the transformed props for `field` via `Field.props()`. Throws if
+     * the field key does not exist in this form's shape, making typos a runtime
+     * error rather than a silent no-op.
+     */
+    register(field: FieldPaths<T>): import("..").IFieldProps;
+    use<Selected>(selector: FormSelector<T, Selected>): Selected;
+    useReset(): void;
+    useShared<Selected>(selector: FormSelector<T, Selected>): Selected;
+}
+/**
+ * Creates a `Form` instance that is stable for the lifetime of the component
+ * (memoised on `name`). Use this when the form is local to a single mounted
+ * component. For forms that must survive unmounts (e.g. multi-step flows),
+ * construct the `Form` outside React via `form()`.
+ *
+ * Note: `def` is only read on the first render — changing it after mount has
+ * no effect.
+ */
+export declare function useForm<T extends FormDef>(name: string, def: T): Form<T>;
+/**
+ * Constructs a `Form` outside of React — suitable for module-level singletons,
+ * server-side construction, or multi-step flows where the form must outlive
+ * any individual component. Values are **not** automatically reset on unmount;
+ * call `resetValues()` explicitly when needed.
+ */
+export declare function form<Def extends FormDef>(...args: ConstructorParameters<typeof Form<Def>>): Form<Def>;
+export {};
+//# sourceMappingURL=Form.d.ts.map

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

@@ -0,0 +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"}

package/dist/lib/factories.d.ts

@@ -0,0 +1,14 @@
+import { Validator } from "../types";
+import { Field } from "./Field";
+type FieldBuilder<T, Validate extends Validator<any, any, any>> = typeof Field<T, Validate>;
+/**
+ * Wraps a `Field` subclass constructor in a factory function, eliminating the
+ * need to call `new` at the call site and improving inference of the
+ * `validate` option's generic type. The returned factory accepts the same
+ * options as the class constructor and produces a fully typed `Field` instance.
+ *
+ * All entries in the `fields` namespace are built with this helper.
+ */
+export declare function fieldFactory<T extends FieldBuilder<any, any>, Value = T extends FieldBuilder<infer V, any> ? V : never, Validator = T extends FieldBuilder<infer VL, any> ? VL : never>(cls: T): <A extends ConstructorParameters<T>[0]>(options?: A) => Field<Value, A["validate"]>;
+export {};
+//# sourceMappingURL=factories.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"factories.d.ts","sourceRoot":"","sources":["../../src/lib/factories.tsx"],"names":[],"mappings":"AACA,OAAO,EAAW,SAAS,EAAE,MAAM,UAAU,CAAA;AAC7C,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAE/B,KAAK,YAAY,CAAC,CAAC,EAAE,QAAQ,SAAS,SAAS,CAAC,GAAG,EAAC,GAAG,EAAC,GAAG,CAAC,IAAI,OAAO,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAA;AAEzF;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,CAAC,SAAS,YAAY,CAAC,GAAG,EAAC,GAAG,CAAC,EAC/B,KAAK,GAAG,CAAC,SAAS,YAAY,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,EACxD,SAAS,GAAG,CAAC,SAAS,YAAY,CAAC,MAAM,EAAE,EAAE,GAAG,CAAC,GAAG,EAAE,GAAG,KAAK,EAC9D,GAAG,EAAE,CAAC,IACE,CAAC,SAAS,qBAAqB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,KAAG,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC,CAKzF"}

package/dist/lib/index.d.ts

@@ -0,0 +1,3 @@
+export * from './Form';
+export { Field } from './Field';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAA;AACtB,OAAO,EAAC,KAAK,EAAC,MAAM,SAAS,CAAA"}

package/dist/lib/useFieldBinding.d.ts

@@ -0,0 +1,14 @@
+import { IFieldRef } from "../types";
+/**
+ * Attaches an imperative handle to `ref` via `useImperativeHandle`. Every
+ * method in {@link IFieldRef} is given a default implementation that throws
+ * `"ref.<method> not implemented"`, so callers get a clear error rather than a
+ * silent no-op when a method is missing from `impl`.
+ *
+ * `impl` is a partial override — only supply the methods your component
+ * actually supports. Unimplemented methods remain as throwing stubs.
+ * `deps` is forwarded directly to `useImperativeHandle`; include anything
+ * `impl` closes over that can change between renders.
+ */
+export declare function useFieldBinding<T>(ref: React.Ref<IFieldRef<T> | null> | undefined, impl: Partial<IFieldRef<T>>, deps?: React.DependencyList): void;
+//# sourceMappingURL=useFieldBinding.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useFieldBinding.d.ts","sourceRoot":"","sources":["../../src/lib/useFieldBinding.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAEpC;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,SAAS,EAAE,IAAI,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,GAAE,KAAK,CAAC,cAAmB,QAoC/I"}

package/dist/types/field.d.ts

@@ -0,0 +1,22 @@
+import { WritableStore } from 'nanostores';
+import { Validator } from './validation';
+export type FieldState<T> = WritableStore<T>;
+export interface ExtraFieldOptions {
+}
+export type FieldOptions<T, Validate extends Validator<T, any, any>> = {
+    name?: string;
+    defaultValue?: T | null;
+    state?: FieldState<T>;
+    validate?: Validate;
+    loader?: (form: any) => Partial<Omit<FieldOptions<T, Validate>, 'loader'>>;
+    onValueChange?: (newValue: T) => void;
+} & ExtraFieldOptions;
+export type FieldMeasureResult = {
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    pageX?: number;
+    pageY?: number;
+};
+//# sourceMappingURL=field.d.ts.map

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

@@ -0,0 +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"}

package/dist/types/form.d.ts

@@ -0,0 +1,26 @@
+import { Field } from "../lib/Field";
+import { ValidationResult } from "./validation";
+export type FormDef = Record<string, Field<any, any>>;
+export type NarrowKeyof<T> = Extract<keyof T, string>;
+export type FormValues<T extends FormDef> = {
+    [K in NarrowKeyof<T>]: T[K]['value'];
+};
+export type FormErrors<T extends FormDef> = {
+    [K in NarrowKeyof<T>]: ReturnType<T[K]['validate']> extends ValidationResult<any, infer E> ? E : never;
+};
+export type FormResults<T extends FormDef> = {
+    [K in NarrowKeyof<T>]: ReturnType<T[K]['validate']> extends ValidationResult<infer R, any> ? R : never;
+};
+export type FieldTuples<T extends FormDef> = {
+    [K in NarrowKeyof<T>]: [K, T[K]];
+}[NarrowKeyof<T>];
+export type PropertyForKeys<T extends FormDef, Keys extends FieldPaths<T>, Property extends keyof Field<any, any>> = {
+    [K in Keys]: T[K][Property];
+};
+export type FieldPropertyTuples<T extends FormDef, Property extends keyof Field<any, any>> = {
+    [K in NarrowKeyof<T>]: [K, T[K][Property]];
+}[NarrowKeyof<T>];
+export type FieldPaths<T extends FormDef> = ({
+    [K in NarrowKeyof<T>]: K;
+})[NarrowKeyof<T>];
+//# sourceMappingURL=form.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"form.d.ts","sourceRoot":"","sources":["../../src/types/form.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAA;AACpC,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAE/C,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAG,KAAK,CAAC,GAAG,EAAC,GAAG,CAAC,CAAC,CAAA;AAErD,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAA;AAErD,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,OAAO,IAAI;KACzC,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,GAAI,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;CACtC,CAAA;AAED,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,OAAO,IAAI;KACzC,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,GAAI,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,SAAS,gBAAgB,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK;CACxG,CAAA;AAED,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,OAAO,IAAI;KAC1C,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,GAAI,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,SAAS,gBAAgB,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK;CACxG,CAAA;AAED,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,OAAO,IAAI;KAC1C,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;CACjC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAA;AAEjB,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,OAAO,EAAE,IAAI,SAAS,UAAU,CAAC,CAAC,CAAC,EAAG,QAAQ,SAAS,MAAM,KAAK,CAAC,GAAG,EAAC,GAAG,CAAC,IAAI;KAClH,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;CAC5B,CAAA;AAED,MAAM,MAAM,mBAAmB,CAAC,CAAC,SAAS,OAAO,EAAE,QAAQ,SAAS,MAAM,KAAK,CAAC,GAAG,EAAC,GAAG,CAAC,IAAI;KACzF,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;CAC3C,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAA;AAIjB,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,OAAO,IAAI,CAAC;KAC1C,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC;CACzB,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAA"}

package/dist/types/globals.d.ts

@@ -0,0 +1,15 @@
+import { AnyRecord } from '@codeleap/types';
+export interface IFieldRef<T> {
+    getValue(): T;
+    scrollIntoView(): Promise<void>;
+    focus(): void;
+    blur(): void;
+    revealValue(): void;
+    toggleValueVisibility(): void;
+    hideValue(): void;
+    emit(event: string, ...args: any[]): void;
+}
+export interface IFieldProps {
+}
+export type PropTransformer = (props: AnyRecord) => AnyRecord;
+//# sourceMappingURL=globals.d.ts.map

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

@@ -0,0 +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"}

package/dist/types/index.d.ts

@@ -0,0 +1,5 @@
+export type * from './field';
+export type * from './form';
+export type * from './validation';
+export type * from './globals';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,SAAS,CAAA;AAC5B,mBAAmB,QAAQ,CAAA;AAC3B,mBAAmB,cAAc,CAAA;AACjC,mBAAmB,WAAW,CAAA"}

package/dist/types/validation.d.ts

@@ -0,0 +1,9 @@
+export type ValidationResult<Result, Err> = {
+    isValid: boolean;
+    result?: Result;
+    error?: Err;
+    readableError?: string;
+};
+export type ValidatorFunction<Value, Result, Err> = (value: Value, form: any) => ValidationResult<Result, Err>;
+export type Validator<Value, Result, Err> = ValidatorFunction<Value, Result, Err>;
+//# sourceMappingURL=validation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/types/validation.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,CAAC,MAAM,EAAE,GAAG,IAAI;IAC1C,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,GAAG,CAAA;IACX,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAED,MAAM,MAAM,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,KAAK,gBAAgB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;AAE9G,MAAM,MAAM,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,CAAA"}

package/dist/validators/index.d.ts

@@ -0,0 +1,2 @@
+export * from './zod';
+//# sourceMappingURL=index.d.ts.map

package/dist/validators/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/validators/index.ts"],"names":[],"mappings":"AAAA,cAAc,OAAO,CAAA"}

package/dist/validators/zod.d.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import { ValidationResult } from '../types';
+type ZodValidationResult<T extends z.ZodType> = ValidationResult<z.infer<T>, z.ZodError['issues']>;
+/**
+ * Adapts a Zod schema into the `Validator` contract expected by `Field` and
+ * `useValidate`. Uses `safeParse` internally so Zod errors are captured as
+ * `{ isValid: false, error: ZodIssue[] }` rather than thrown exceptions.
+ *
+ * The returned function is synchronous — async Zod schemas (`z.promise`,
+ * `.parseAsync`) are not supported.
+ */
+export declare function zodValidator<T extends z.ZodType>(model: T): (value: unknown) => ZodValidationResult<T>;
+/**
+ * Type guard that narrows a `ValidationResult`-shaped value to one produced by
+ * `zodValidator`. A valid result must have `result` present; an invalid result
+ * must have `error` as an array of `ZodIssue` objects. Use this to
+ * distinguish Zod results from results produced by custom validators when
+ * handling errors generically.
+ */
+export declare function isZodValidationResult(val: any): val is ZodValidationResult<any>;
+export {};
+//# sourceMappingURL=zod.d.ts.map

package/dist/validators/zod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod.d.ts","sourceRoot":"","sources":["../../src/validators/zod.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAY,MAAM,KAAK,CAAA;AACjC,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AAG3C,KAAK,mBAAmB,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,IAAI,gBAAgB,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAA;AAElG;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC,IAChD,OAAO,OAAO,KAAG,mBAAmB,CAAC,CAAC,CAAC,CAShD;AAOD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,GAAG,GAAG,GAAG,IAAI,mBAAmB,CAAC,GAAG,CAAC,CAa/E"}

package/package.json

@@ -1,7 +1,20 @@
 {
   "name": "@codeleap/form",
-  "version": "6.3.0",
+  "version": "6.8.0",
   "main": "src/index.ts",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
   "license": "UNLICENSED",
   "repository": {
     "url": "https://github.com/codeleap-uk/internal-libs-monorepo.git",
@@ -9,22 +22,25 @@
     "directory": "packages/form"
   },
   "devDependencies": {
-    "@codeleap/config": "6.3.0",
-    "@codeleap/types": "6.3.0",
-    "@codeleap/store": "6.3.0",
-    "zod": "3.23.8",
+    "@codeleap/config": "6.8.0",
+    "@codeleap/types": "6.8.0",
+    "@codeleap/store": "6.8.0",
+    "@codeleap/hooks": "6.8.0",
+    "zod": "4.4.3",
     "ts-node-dev": "1.1.8"
   },
   "scripts": {
-    "build": "echo 'No build needed'",
+    "build": "tsc --build tsconfig.build.json",
+    "typecheck": "bun tsc --noEmit -p ./tsconfig.json",
     "playground": "bun src/test.ts"
   },
   "peerDependencies": {
-    "@codeleap/types": "6.3.0",
-    "@codeleap/store": "6.3.0",
-    "@codeleap/logger": "6.3.0",
+    "@codeleap/types": "6.8.0",
+    "@codeleap/store": "6.8.0",
+    "@codeleap/logger": "6.8.0",
+    "@codeleap/hooks": "6.8.0",
     "zod": "*",
     "react": "19.1.0",
     "typescript": "5.5.2"
   }
-}
+}

package/src/fields/bool.ts

@@ -5,10 +5,16 @@ import { zodValidator } from "../validators"
 
 type VALUE = boolean
 
+/** Validator signature for boolean-valued fields. */
 export type BooleanValidator<R = any, Err = any> = Validator<VALUE, R, Err>
 
 type BooleanFieldOptions<Validate extends BooleanValidator> = FieldOptions<VALUE, Validate>
 
+/**
+ * Field for boolean values (checkboxes, toggles). `Form.setValues` treats
+ * this field specially: it will only set a value when the incoming value is
+ * strictly `boolean`, because falsy coercion would prevent setting `false`.
+ */
 export class BooleanField<Validate extends BooleanValidator> extends Field<boolean, Validate> {
   _type = "BOOLEAN"
 

package/src/fields/date.ts

@@ -4,6 +4,7 @@ import { FieldOptions, Validator } from "../types"
 import { zodValidator } from "../validators"
 import dayjs from 'dayjs'
 
+/** Validator signature for `Date`-valued fields. */
 export type DateValidator<R = any, Err = any> = Validator<Date, R, Err>
 
 type DateFieldOptions<Validate extends DateValidator> = FieldOptions<Date, Validate> & {
@@ -24,6 +25,14 @@ function normalizeToDate(val: unknown): Date | undefined {
   return undefined
 }
 
+/**
+ * Field for `Date` values with optional `minimumDate` / `maximumDate` bounds.
+ * The built-in validator normalises the raw input via `dayjs` before running
+ * boundary checks, so it transparently accepts `Date` objects, dayjs instances,
+ * and ISO date strings. Invalid or unparseable values are normalised to
+ * `undefined`, which fails the `z.date()` check. Bounds are enforced at the
+ * start of the day (`startOf('day')`) for dayjs inputs.
+ */
 export class DateField<Validate extends DateValidator> extends Field<Date, Validate> {
   _type = "DATE"
 

package/src/fields/file.ts

@@ -3,10 +3,17 @@ import { z } from 'zod'
 import { FieldOptions, Validator } from "../types"
 import { zodValidator } from "../validators"
 
+/** Validator signature for file-valued fields. The value type is intentionally `any` to accommodate platform-specific file objects (web `File`, React Native asset objects, etc.). */
 export type FileValidator<R = any, Err = any> = Validator<any, R, Err>
 
 type FileFieldOptions<Validate extends FileValidator> = FieldOptions<any, Validate>
 
+/**
+ * Field for file uploads. The value type is `any` because the shape of a
+ * "file" differs between web (`File` / `FileList`) and React Native (asset
+ * descriptor objects). Supply a custom `validate` function to enforce whatever
+ * shape your platform produces.
+ */
 export class FileField<Validate extends FileValidator> extends Field<any, Validate> {
   _type = "FILE"
 

package/src/fields/group.ts

@@ -9,6 +9,12 @@ type GroupValidator<R = any, Err = any> = Validator<VALUE, R, Err>
 
 type GroupFieldOptions<Validate extends GroupValidator> = FieldOptions<VALUE, Validate>
 
+/**
+ * Field that represents a selected group or category, stored as a string key.
+ * Structurally identical to `TextField` but carries the `"group"` type tag so
+ * platform renderers can distinguish it and render a group-picker control
+ * instead of a free-text input.
+ */
 export class GroupField<Validate extends GroupValidator> extends Field<string, Validate> {
   _type = "group"
 

package/src/fields/index.ts

@@ -1,15 +1,30 @@
 import { fieldFactory } from "../lib/factories"
 import { TextField } from "./text"
-import { ListField } from "./list"
+import { ListField,  listFieldFactory} from "./list"
 import { NumberField } from "./number"
 import { BooleanField } from "./bool"
 import { SelectableField } from "./selectable"
 import { DateField } from "./date"
 import { FileField } from "./file"
 
+
+/**
+ * Convenience namespace that exposes factory functions for every built-in field
+ * type. Prefer these over calling constructors directly — they provide better
+ * generic inference for the `validate` option.
+ *
+ * ```ts
+ * const emailField = fields.text({ validate: zodValidator(z.string().email()) })
+ * const tagsField  = fields.list({ item: fields.text(), defaultValue: [] })
+ * ```
+ *
+ * Note: `fields.list` is the only entry that is not wrapped with
+ * `fieldFactory`, because `ListField` requires the `item` option's type to be
+ * inferred at the call site.
+ */
 export const fields = {
   text: fieldFactory(TextField),
-  list: fieldFactory(ListField),
+  list: listFieldFactory,
   number: fieldFactory(NumberField),
   boolean: fieldFactory(BooleanField),
   selectable: fieldFactory(SelectableField),

package/src/fields/list.ts

@@ -1,36 +1,85 @@
 import { Field } from "../lib/Field"
 import { FieldOptions, Validator } from "../types"
 
-export type ListValidator<Val, R = any, Err = any> = Validator<Val[] | Val, R, Err>
+/** 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 ListFieldOptions<T, Validate extends Validator<T | T[], any, any>> = FieldOptions<T, Validate> & {
-  item: Field<T, Validate>
-}
+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
 
-export class ListField<T, Validate extends ListValidator<T>> extends Field<T | T[], Validate> {
+export type ListFieldOptions<ItemField extends Field<any, any>> = {
+  item: ItemField
+}  & _ListFieldOptions<ItemField>
+
+/**
+ * Field that holds an array of values, each validated by a delegate `item`
+ * field. The built-in validator iterates every element through
+ * `options.item.validate` and collects all failures into an error array. The
+ * list is considered valid only when every element passes. If `item` has no
+ * validator, the list is always valid.
+ *
+ * The `item` field acts as a prototype — it is not mounted independently and
+ * 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"
 
-  constructor(options: ListFieldOptions<T[] | T, Validate>) {
+  constructor(options: ListFieldOptions<T>) {
     super({
-      // @ts-ignore fix this
-      validate: (v) => {
-        if (!options.validate) return {
+      ...options,
+      validate: ((v, form) => {
+        if (!options.item?.validate) return {
           isValid: true
         }
 
-        for (const value of v as T[]) {
-          const validation = options.validate?.(value, null)
+        const errors = []
+
+        for (const value of v) {
+          const validation = options.item?.validate?.(value)
 
           if (!validation.isValid) {
-            return validation
+            errors.push(validation)
+          }
+        }
+
+        if (errors.length) {
+          return {
+            isValid: false,
+            error: errors,
           }
         }
 
         return {
-          isValid: true
+          isValid: true,
         }
-      },
-      ...options
-    })
+      }) as AsListValidator<T>,
+    } as unknown as FieldOptions<ExtractFieldValue<T>[], AsListValidator<T>>)
   }
-}
+}
+
+/**
+ * Convenience factory for `ListField`. Unlike `fieldFactory`-based helpers,
+ * `ListField` requires an `item` option whose generic type must be inferred at
+ * the call site, so it cannot share the same factory wrapper. This function
+ * 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> {
+  return new ListField(options)
+} 

package/src/fields/number.ts

@@ -3,6 +3,7 @@ import { z } from 'zod'
 import { FieldOptions, Validator } from "../types"
 import { zodValidator } from "../validators"
 
+/** Validator signature for numeric fields. Accepts either a single number or an array of numbers (for range inputs). */
 export type NumberValidator<R = any, Err = any> = Validator<number | number[], R, Err>
 
 type Props = {
@@ -14,6 +15,14 @@ type NumberFieldOptions<Validate extends NumberValidator> = FieldOptions<number
 
 const MAX_VALID_DIGITS = 1000000000000000 // maximum number of digits that the input supports to perform operations
 
+/**
+ * Field for numeric values. Supports both single numbers and arrays of numbers
+ * (range / multi-handle sliders) — the mode is inferred from whether
+ * `defaultValue` is an array. `min` defaults to `0` and `max` defaults to
+ * `1_000_000_000_000_000` (the maximum safe integer range the underlying input
+ * supports for arithmetic operations). Values outside the range fail
+ * validation.
+ */
 export class NumberField<Validate extends NumberValidator> extends Field<number | number[], Validate> {
   _type = "NUMBER"
 

package/src/fields/selectable.ts

@@ -6,6 +6,7 @@ import { Options } from '@codeleap/types'
 
 type VALUE = string | number
 
+/** Validator signature for selectable fields whose value is a `string` or `number` key. */
 export type SelectableValidator<V extends VALUE, R = any, Err = any> = Validator<V, R, Err>
 
 type SelectableFieldOptions<V extends VALUE, Validate extends SelectableValidator<V>> = FieldOptions<V, Validate> & {
@@ -14,6 +15,14 @@ type SelectableFieldOptions<V extends VALUE, Validate extends SelectableValidato
   maxItems?: number
 }
 
+/**
+ * Field for single or multi-select inputs whose options are a fixed list of
+ * string/number keys. `minItems` defaults to `1` (at least one selection
+ * required) and `maxItems` defaults to the length of the provided `options`
+ * array (all items selectable). The built-in validator accepts either a single
+ * value or an array, so the same field type covers both radio-style and
+ * checkbox-style UIs.
+ */
 export class SelectableField<V extends VALUE, Validate extends SelectableValidator<V>> extends Field<V, Validate> {
   _type = "SELECTABLE"
 

package/src/fields/text.ts

@@ -5,6 +5,7 @@ import { zodValidator } from "../validators"
 
 type VALUE = string
 
+/** Validator signature for string-valued fields. */
 export type TextValidator<R = any, Err = any> = Validator<VALUE, R, Err>
 
 type TextFieldOptions<Validate extends TextValidator> = FieldOptions<VALUE, Validate> & {
@@ -12,12 +13,18 @@ type TextFieldOptions<Validate extends TextValidator> = FieldOptions<VALUE, Vali
   multiline?: boolean
 }
 
+/**
+ * Field for plain string values. Ships with a `z.string()` fallback validator
+ * so the field is always valid when no custom `validate` option is provided.
+ * Accepts `secure` (password masking) and `multiline` hints that are forwarded
+ * as props to the underlying input component.
+ */
 export class TextField<Validate extends TextValidator> extends Field<string, Validate> {
   _type = "TEXT"
 
   constructor(options: TextFieldOptions<Validate>) {
     super({
-      validate: zodValidator(z.string()) as unknown as Validate,
+      validate: zodValidator(z.string().optional()) as unknown as Validate,
       ...options
     })
   }