@codeleap/form 6.3.0 → 6.8.0

package/src/hooks/useField.ts

@@ -1,6 +1,19 @@
 import { useMemo } from "react"
 import type { Field } from "../lib"
 
+/**
+ * Convenience hook for components that accept an optional `field` prop. When
+ * `field` is provided it is used directly; when it is absent (falsy), a
+ * temporary field created by `defaultField` is memoised for the component's
+ * lifetime.
+ *
+ * This lets components remain uncontrolled by default (using their own
+ * internal field) while still accepting external control when a `field` prop
+ * is supplied — without conditional hook calls.
+ *
+ * `params` are forwarded to `field.use()` in either branch, so imperative
+ * ref bindings work regardless of which field is active.
+ */
 export function useField<V, T extends Field<V, any, any>>(field: T, params: Parameters<T['use']>, defaultField: () => T): ReturnType<T['use']> {
   if (field) {
     return field.use(params?.[0], params?.[1]) as ReturnType<T['use']>

package/src/hooks/useValidate.ts

@@ -2,6 +2,22 @@ import { useCallback, useRef, useState } from 'react'
 import { Validator } from '../types'
 import { ValidationError } from '../lib/Field'
 
+/**
+ * Standalone validation hook for values managed outside a `Field` instance.
+ * Useful when you have a raw state value and a validator function but do not
+ * want to create a full `Field` object.
+ *
+ * Error display follows the same blur policy as `Field.useValidation`: if
+ * `value` is `undefined` on the first render (`startedUnset`), the error is
+ * hidden until the user has blurred the input. Call the returned
+ * `onInputBlurred` handler on the input's blur event to trigger visibility.
+ *
+ * `message` is resolved from `readableError` first, then from the first
+ * element's `.message` when `error` is an array.
+ *
+ * A {@link ValidationError} thrown by `providedValidate` is caught and
+ * normalised; other exceptions propagate.
+ */
 export const useValidate = <T, V extends Validator<T, any, any>>(value: T, providedValidate: V) => {
   const [hasBlurred, setHasBlurred] = useState(false)
 

package/src/lib/Field.ts

@@ -1,7 +1,7 @@
 import { FieldState, FieldOptions, FieldMeasureResult } from '../types/field';
 import { ValidationResult, Validator } from '../types/validation';
-import { IFieldRef,  IFieldProps } from '../types/globals';
-import { atom }  from 'nanostores'
+import { IFieldRef,  IFieldProps, PropTransformer } from '../types/globals';
+import { Atom, atom, WritableAtom }  from 'nanostores'
 import { AnyRecord, SecondToLastArguments, TypeGuards } from '@codeleap/types';
  
 import { useStore } from '@nanostores/react'
@@ -9,6 +9,14 @@ import { useFieldBinding } from './useFieldBinding';
 import { createRef, useRef, useState } from 'react';
 import { logger } from '@codeleap/logger';
 
+/**
+ * Thrown inside a validator function to signal a structured validation failure
+ * without propagating as an unhandled exception. The `data` payload is forwarded
+ * verbatim as the `error` field of the resulting {@link ValidationResult}.
+ *
+ * Throw this instead of returning `{ isValid: false }` when you need to exit
+ * validation from a nested helper that cannot easily return a value.
+ */
 export class ValidationError extends Error {
   data: any
 
@@ -20,27 +28,62 @@ export class ValidationError extends Error {
 
 
 
+/**
+ * Base class for all form fields. Owns the nanostores atom that holds the
+ * field's current value, runs synchronous validation on demand, and exposes
+ * React hooks (`use`, `useValue`, `useValidation`) that components call to
+ * subscribe to reactive updates.
+ *
+ * **Validation lifecycle**
+ * Validation is always synchronous and called eagerly — there is no deferred
+ * or debounced step. `validate()` runs against the current atom value each
+ * time it is called, so repeated calls are cheap but not memoised. Error
+ * visibility is decoupled from validity: errors are hidden until
+ * `revealError()` is called (or the field has been blurred while starting
+ * with an undefined value), allowing UX to control when messages appear.
+ *
+ * **Initialization order constraint**
+ * The constructor calls `loadState()` synchronously. If `defaultValue` is a
+ * Promise or a function that returns a Promise, the atom is initialised with
+ * `undefined` immediately and the resolved value is set asynchronously once
+ * the promise settles. Do not read `initialValue` before the promise resolves.
+ *
+ * **Platform methods**
+ * `measurePosition`, `scrollTo`, and `getPadding` delegate to static method
+ * slots (`methodMeasurePosition`, `methodScrollTo`, `methodGetPadding`) that
+ * must be assigned by the platform layer (web or mobile) before use; calling
+ * them without an implementation throws.
+ *
+ * **Prop transformers**
+ * `props()` pipes the field's properties through every registered transformer
+ * in insertion order. Transformers are global and shared across all field
+ * instances via `Field.transformers`.
+ */
 export class Field<
-  T, 
+  T,
   Validate extends Validator<T,any,any>,
   Result  = Validate extends Validator<T, infer R, any> ? R : never,
   Err  = Validate extends Validator<T, any, infer E> ? E : never
 > {
-  _type: string
+  _type!: string
 
-  deep: boolean
+  deep!: boolean
 
-  state: FieldState<T>
+  state!: FieldState<T>
+
+  errorRevealed: WritableAtom<boolean>
 
   properties: AnyRecord = {}
 
+  static transformers: Map<string, PropTransformer> = new Map()
+
   options: FieldOptions<T, Validate>
 
-  ref?: React.RefObject<IFieldRef<T>>
+  ref?: React.RefObject<IFieldRef<T> | null>
 
-  __validationRes: ValidationResult<Result, Err>
+  __validationRes!: ValidationResult<Result, Err>
 
-  private initialValue: T
+  private initialValue!: T
 
   static enableLogs = false
 
@@ -60,14 +103,40 @@ export class Field<
     throw new Error('Field.getPadding not implemented')
   }
 
+  /**
+   * Marks the field's error as visible. Typically called by `Form.validate`
+   * when `revealErrors: true` is passed, or imperatively after a failed submit.
+   * Has no effect on the underlying validity — only on whether the error
+   * message is shown to the user.
+   */
+  revealError(){
+    this.errorRevealed.set(true)
+  }
+
+  /**
+   * Resets error visibility to hidden without changing the field's value or
+   * validity state. Useful when clearing a form section programmatically
+   * while preserving the current value.
+   */
+  hideError(){
+    this.errorRevealed.set(false)
+  }
+
+  get isErrorRevealed(){
+    return this.errorRevealed.get()
+  }
+
   constructor(options: FieldOptions<T, Validate>) {
     this.options = options
     this.ref = createRef()
     this.loadState()
+    this.errorRevealed = atom(false)
 
     this.setValue = this.setValue.bind(this)
     this.use = this.use.bind(this)
     this.useBinding = this.useBinding.bind(this)
+    this.revealError = this.revealError.bind(this)
+    this.hideError = this.hideError.bind(this)
 
     this.properties = this.toInternalProperties(options)
   }
@@ -89,12 +158,24 @@ export class Field<
   private toInternalProperties(options: FieldOptions<T, Validate>) {
     const internalKeys = new Set(['name', 'defaultValue', 'state', 'validate', 'loader', 'onValueChange'])
 
+    const values = {
+      name: this.name,
+      ...Object.fromEntries(Object.entries(options).filter(([key]) => !internalKeys.has(key)))
+    }
+
     return Object.assign(
       { field: this },
-      Object.fromEntries(Object.entries(options).filter(([key]) => !internalKeys.has(key)))
+      values
+      
     )
   }
 
+  /**
+   * Replaces the field's internal atom with a slice of the owning `Form`'s
+   * global state atom and migrates the current value into it. Called
+   * automatically by `Form.attachState()` during construction — do not call
+   * this manually unless you are building a custom form container.
+   */
   attach(to: FieldState<T>) {
     const val = this.value
 
@@ -116,8 +197,19 @@ export class Field<
 
   resetValue() {
     this.setValue(this.initialValue)
+    this.errorRevealed.set(false)
   }
 
+  /**
+   * Primary React hook for consuming a field inside a component. Subscribes to
+   * the field's value atom and validation state, and optionally wires an
+   * imperative ref handle via `useFieldBinding`. Must be called
+   * unconditionally at the component's top level.
+   *
+   * The `changed` flag compares the current value to the value captured at
+   * field construction time (or after the last `resetValue`), not to any
+   * previous render.
+   */
   use(impl?: Partial<IFieldRef<T>>, deps?: any[]){
     const value = this.useValue()    
 
@@ -151,24 +243,24 @@ export class Field<
 
   // If we make this async, the js engine will not delay further execution while the funcion is not done. This way we wait until we know wheter there's a promise or not
   loadState(){
-    let defaultValuePromise: Promise<T> = undefined
-    let defaultValue:T = undefined
+    let defaultValuePromise: Promise<T> | undefined = undefined
+    let defaultValue: T = undefined as T
 
     if(TypeGuards.isFunction(this.options.defaultValue)) {
       const v = this.options.defaultValue()
 
       if(TypeGuards.isPromise(v)) {
-        defaultValuePromise = v
+        defaultValuePromise = v as Promise<T>
       } else {
-        defaultValue = v    
+        defaultValue = v as T
       }
     } else {
       const v = this.options?.defaultValue
 
       if(TypeGuards.isPromise(v)) {
-        defaultValuePromise = v
+        defaultValuePromise = v as Promise<T>
       } else {
-        defaultValue = v    
+        defaultValue = v as T
       }
     }
 
@@ -214,6 +306,15 @@ export class Field<
     return logArgs
   }
 
+  /**
+   * Runs the field's validator synchronously against `value` (or the current
+   * atom value when omitted). A {@link ValidationError} thrown inside the
+   * validator is caught and converted to `{ isValid: false, error: e.data }`;
+   * any other exception is re-thrown.
+   *
+   * This method is called on every render inside `useValidation` — keep
+   * validators fast and free of side effects.
+   */
   validate(value?: any): ValidationResult<Result, Err> {
     
     const validate = this.options.validate
@@ -221,8 +322,8 @@ export class Field<
     const valueToCheck = TypeGuards.isUndefined(value) ? this.state.get() : this.toInternalValue(value)
   
     try {
-      const result = validate(valueToCheck, {})
-            
+      const result = validate!(valueToCheck, {})
+
       return result
 
     } catch(e) {
@@ -239,8 +340,22 @@ export class Field<
     
   }
 
+  /**
+   * React hook that returns reactive validation state for the field's current
+   * value. Error display policy:
+   * - If the field started with an `undefined` value (`startedUnset`), the
+   *   error is hidden until the user has blurred the input **or** until
+   *   `revealError()` has been called.
+   * - If the field started with a defined value, the error is shown
+   *   immediately whenever the field is invalid.
+   *
+   * `message` is resolved from `readableError` first, falling back to the
+   * first element's `.message` when `error` is an array.
+   */
   useValidation() {
     const value = this.useValue()
+
+    const revealed = useStore(this.errorRevealed)
     
     const isUnset = typeof value === 'undefined'
 
@@ -256,14 +371,15 @@ export class Field<
 
     const hasChanged = this.initialValue != value
     
-    const message = validation.readableError ?? validation.error?.[0]?.message
+    const message = validation.readableError ?? (Array.isArray(validation.error) ? validation.error[0]?.message : undefined)
 
     const errorDisplayRequiresBlur = startedUnset
 
     
     const [hasBlurred, setHasBlurred] = useState(false)
 
-    const showError = isInvalid && (errorDisplayRequiresBlur ? hasBlurred : true)
+    const showError = isInvalid && (
+      errorDisplayRequiresBlur ? revealed || hasBlurred : true)
 
     
 
@@ -286,7 +402,7 @@ export class Field<
   }
 
   log(level = 'log', ...args: any[]){
-    if (Field.enableLogs) logger[level](...this.formatLog(...args))
+    if (Field.enableLogs) (logger as unknown as Record<string, (...args: any[]) => void>)[level](...this.formatLog(...args))
   }
   
   toInternalValue(v: any) {
@@ -297,8 +413,36 @@ export class Field<
     return v as any
   }
 
+  /**
+   * Registers a global prop transformer under `key`. Transformers are applied
+   * in insertion order by `props()`. Re-registering an existing key replaces
+   * the previous function.
+   */
+  static attachTransformer(key: string, fn: PropTransformer) {
+    Field.transformers.set(key, fn)
+  }
+
+  /**
+   * Removes the transformer registered under `key`. Idempotent — no-op if the
+   * key is not present.
+   */
+  static detachTransformer(key: string) {
+    Field.transformers.delete(key)
+  }
+
+  /**
+   * Returns the field's properties after running them through every registered
+   * global transformer. The raw `properties` object is built from `options`
+   * with internal keys (`name`, `defaultValue`, `state`, `validate`, `loader`,
+   * `onValueChange`) stripped out, plus a `field` reference to `this`.
+   * Use this when passing field metadata to a component that does not use the
+   * `use()` hook directly.
+   */
   props(): IFieldProps {
-    return this.properties
+    return Array.from(Field.transformers.values()).reduce<AnyRecord>(
+      (acc, transformer) => transformer(acc),
+      this.properties,
+    ) as IFieldProps
   }
 
   measurePosition<T>(wrapperRef: T): Promise<FieldMeasureResult> {

package/src/lib/Form.ts

@@ -2,12 +2,13 @@ import { createStateSlice, GlobalState, globalState } from "@codeleap/store"
 import { TypeGuards } from "@codeleap/types"
 import { DependencyList, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react"
 import { FieldPaths, FieldPropertyTuples, FieldTuples, FormDef, FormValues, PropertyForKeys, ValidationResult } from "../types"
+import { useUnmount } from "@codeleap/hooks"
 
 
 
 
 function buildState<T extends FormDef>(def: T) {
-  const stateArg = {}
+  const stateArg: Record<string, unknown> = {}
 
   for(const [name, field] of Object.entries(def)) {
     stateArg[name] = field.value
@@ -21,6 +22,30 @@ 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.
+ */
 class Form<T extends FormDef> {
   id: string
   fields: T
@@ -36,30 +61,45 @@ class Form<T extends FormDef> {
     )
 
     this.attachState()
-  
+    this.use = this.use.bind(this)
+    this.useShared = this.useShared.bind(this)
+    this.useReset = this.useReset.bind(this)
   }
 
   get values(){
     return this.state.get()
   }
 
+  get isChanged(){
+    return this.changed()
+  }
+
+
+  changed(){
+    for(const [fieldName, field] of Object.entries(this.fields)){
+      if(field.changed()) return true
+    }
+
+    return false
+  }
+
   get isValid(){
     const res = this.validate()
 
-    return Object.values(res).every((result: ValidationResult<any, any>) => result.isValid)
+    return (Object.values(res) as ValidationResult<any, any>[]).every((result) => result.isValid)
   }
 
   slice<K extends FieldPaths<T>>(field: K) {
     
     const fieldSlice = createStateSlice(
-      this.state, 
-      (v) => v[field], 
+      this.state,
+      (v) => (v as Record<string, unknown>)[field as string],
       (value) => {
         return {
           [field]: value
         } as FormValues<T>
       }
-      
+
     )
 
     return fieldSlice
@@ -80,6 +120,11 @@ class Form<T extends FormDef> {
     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.
+   */
   setValues(values: Partial<FormValues<T>>) {
     this.iterFields(([name, field]) => {
       const value = values?.[name]
@@ -104,6 +149,11 @@ class Form<T extends FormDef> {
     })
   }
 
+  /**
+   * 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() {
     for(const [fieldName, field] of Object.entries(this.fields)){
       const validation = field.validate()
@@ -115,7 +165,9 @@ class Form<T extends FormDef> {
     }
   }
 
-  validate<Fields extends FieldPaths<T>[] = FieldPaths<T>[]>(fields?: Fields): PropertyForKeys<T, Fields[number], '__validationRes'> {
+  validate<Fields extends FieldPaths<T>[] = FieldPaths<T>[]>(options?: { fields?: Fields, revealErrors?: boolean }): PropertyForKeys<T, Fields[number], '__validationRes'> {
+
+    const { fields, revealErrors } = options ?? {}
 
     const validateFields = fields ?? Object.keys(this.fields)
 
@@ -126,14 +178,25 @@ class Form<T extends FormDef> {
     })
 
     const resultMap = Object.fromEntries(
-      results.filter(v => !TypeGuards.isNil(v))
+      results.filter((v): v is FieldPropertyTuples<T, '__validationRes'> => !TypeGuards.isNil(v))
     )
 
+    if(revealErrors){
+      this.iterFields(([_,field]) => {
+        field.revealError()
+      })
+    }
+
     return resultMap as unknown as 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>) {
     if(!this.fields[field]){
       throw new Error(`Field "${field}" not found in "${this.id}" form`)
@@ -141,13 +204,20 @@ class Form<T extends FormDef> {
     return this.fields[field].props()
   }
 
-  useSetValues(formValues?: Partial<FormValues<T>>, deps: DependencyList = []) {
-    useLayoutEffect(() => {
-      if (formValues) this.setValues(formValues)
-    }, deps)
+  use<Selected>(selector: FormSelector<T, Selected>): Selected {
+     const value = this.useShared(selector)
+     
+      this.useReset()
+     
+     return value
   }
 
-  use<Selected>(selector: FormSelector<T, Selected>): Selected {
+  useReset(){
+     useUnmount(() => {
+      this.resetValues()
+     })
+  }
+  useShared<Selected>(selector: FormSelector<T, Selected>): Selected {
     const [selected, setSelected] = useState(() => selector(this))
     
     const reselect = useCallback(() => {
@@ -167,6 +237,15 @@ class Form<T extends FormDef> {
 }
 
 
+/**
+ * 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 function useForm<T extends FormDef>(name: string, def: T) {
   const form = useMemo(() => {
     return new Form(name, def)
@@ -176,6 +255,12 @@ export function useForm<T extends FormDef>(name: string, def: T) {
   return form
 }
 
+/**
+ * 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 function form<Def extends FormDef>(...args: ConstructorParameters<typeof Form<Def>>) {
   return new Form(...args)
 }

package/src/lib/factories.tsx

@@ -4,6 +4,14 @@ 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 function fieldFactory<
   T extends FieldBuilder<any,any>, 
   Value = T extends FieldBuilder<infer V, any> ? V : never, 

package/src/lib/useFieldBinding.ts

@@ -1,10 +1,21 @@
 import { useImperativeHandle } from "react"
 import { IFieldRef } from "../types"
 
-export function useFieldBinding<T>(ref: React.Ref<IFieldRef<T>>, impl: Partial<IFieldRef<T>>, deps = []){
+/**
+ * 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 function useFieldBinding<T>(ref: React.Ref<IFieldRef<T> | null> | undefined, impl: Partial<IFieldRef<T>>, deps: React.DependencyList = []){
 
   const notImplemented = (method: string) => {
-    throw new Error(`ref.${method} not implemented for ${this._type} field`)
+    throw new Error(`ref.${method} not implemented`)
   }
  
 

package/src/types/globals.ts

@@ -1,3 +1,5 @@
+import { AnyRecord } from '@codeleap/types'
+
 export interface IFieldRef<T> {
   getValue(): T
   scrollIntoView(): Promise<void>
@@ -11,5 +13,7 @@ export interface IFieldRef<T> {
 
 
 export interface IFieldProps {
-  
-}
+
+}
+
+export type PropTransformer = (props: AnyRecord) => AnyRecord

package/src/validators/zod.ts

@@ -4,8 +4,16 @@ import { TypeGuards } from '@codeleap/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 function zodValidator<T extends z.ZodType>(model: T) {
-  return (value): ZodValidationResult<T> => {
+  return (value: unknown): ZodValidationResult<T> => {
     const result = model.safeParse(value)
     
     return {
@@ -21,6 +29,13 @@ const isZodIssue = (val: any): val is ZodIssue => {
   return ['code','expected','received','path','message'].every(x => x in val)
 }
 
+/**
+ * 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 function isZodValidationResult(val: any): val is ZodValidationResult<any> {
   const isValidABoolean = TypeGuards.isBoolean(val.isValid)