JSVision

Appearance

@jsvision/forms / Form

Interface: Form<S, I> ​

Defined in: types.ts:59

The headless form store returned by createForm. It owns the raw editing values, validates the whole object through the schema, and exposes per-field and form-level accessors plus submit / reset. It draws nothing.

Type Parameters ​

S ​

S extends z.ZodObject<z.ZodRawShape>

the Zod object schema type.

I ​

I

the raw initial value shape (keys constrained to the schema).

Methods ​

dirty() ​

dirty(): boolean

Defined in: types.ts:76

Whether any field diverges from its baseline.

Returns ​

boolean

dispose() ​

dispose(): void

Defined in: types.ts:126

Tear down the form's whole reactive scope — the standing async-validation effects and every owned computed. Idempotent and safe to call more than once. A long-lived form need not call this, but a per-dialog form that mounts async validators should dispose it when the dialog closes so no debounce fires after teardown.

Returns ​

void

errors() ​

errors(): $ZodIssue[]

Defined in: types.ts:67

Form-level (path-less) validation issues, e.g. from an object-level refine.

Returns ​

$ZodIssue[]

field() ​

field<K>(name): Field<I[K]>

Defined in: types.ts:61

Get the stable handle for a field. Throws FormFieldError for an unknown key.

Type Parameters ​

K ​

K extends string | number | symbol

Parameters ​

name ​

K

Returns ​

Field<I[K]>

isValid() ​

isValid(): boolean

Defined in: types.ts:74

Whether the whole object currently satisfies the schema and has no async error (live, independent of touched). Optimistic about pending async work: a field whose async validator has not yet run (or is still in flight) does not hold this false — only a resolved async error does. Adds no extra safeParse call.

Returns ​

boolean

load() ​

load(loader): Promise<boolean>

Defined in: types.ts:107

Load an existing record into the form: runs loader (given a fresh AbortSignal) and, on success, replaces every field's value and rebases the whole baseline to the loaded record in one batch, leaving the form pristine — touched / submit-attempted cleared and dirty() false, so reset() now returns to the LOADED record. Resolves true on success, false if the loader rejects (state untouched) — it never rejects. Re-invokable (a Reload button). A newer load() supersedes an older in-flight one; dispose() aborts an in-flight load. Do NOT call while a submit() is in flight (the two are independent; gate them in the app).

The loader must resolve the full RAW editing record (Promise<I>, the same shape as initial) — map your server/domain record to raw editing values inside it (there is no inverse of z.coerce). A key missing from the resolved record sets that field (and its baseline) to undefined.

Parameters ​

loader ​

(ctx) => Promise<I>

Returns ​

Promise<boolean>

loading() ​

loading(): boolean

Defined in: types.ts:92

Whether an async record load started by Form.load is currently in flight. Form-level and atomic (a whole record loads at once — there is no per-field loading). It does NOT gate isValid() / submit(); compose the busy state yourself (e.g. disabled: () => form.loading()).

Returns ​

boolean

rawValues() ​

rawValues(): I

Defined in: types.ts:65

The live raw editing snapshot — always available, independent of validity.

Returns ​

I

reset() ​

reset(): void

Defined in: types.ts:119

Restore every field to its baseline value and clear dirty + touched, in one batch.

Returns ​

void

submit() ​

submit(onValid): Promise<boolean>

Defined in: types.ts:117

Mark every field touched, validate, and — when valid — await onValid with the coerced values. Resolves true when valid (after onValid completes) and false when invalid (without calling onValid).

The async-aware gate: it short-circuits false on a synchronously-invalid object (no async validator is invoked), otherwise it cancels pending debounces, force-runs and awaits every async validator, and gates on the combined result — so a value an async rule rejects never passes.

Parameters ​

onValid ​

(values) => void | Promise<void>

Returns ​

Promise<boolean>

submitting() ​

submitting(): boolean

Defined in: types.ts:86

Whether a Form.submit is currently in flight — true synchronously from the moment submit() is called until it settles (its validators and the onValid callback), false on every return path, including a onValid that throws. Form-level; it completes the loading() / validating() / submitting() in-flight trio. Bind a busy indicator or a disabled getter to it (e.g. disabled: () => form.submitting()).

Returns ​

boolean

validating() ​

validating(): boolean

Defined in: types.ts:78

Whether any field is currently running an async validation.

Returns ​

boolean

values() ​

values(): output<S> | null

Defined in: types.ts:63

The coerced, schema-typed values when the form is valid, else null. Never throws.

Returns ​

output<S> | null