@vielzeug/forge 1.1.2

package/dist/types.d.ts

@@ -0,0 +1,391 @@
+/** A callback to remove a subscription. */
+export type Unsubscribe = () => void;
+export type MaybePromise<T> = T | PromiseLike<T>;
+export type FieldValidator<V = unknown> = (value: V, signal?: AbortSignal) => MaybePromise<string | undefined>;
+export type FormValidator<TValues extends Record<string, unknown> = Record<string, unknown>> = (values: TValues, signal?: AbortSignal) => MaybePromise<Partial<Record<ErrorKeyOf<TValues>, string>> | undefined>;
+export type SetOptions = {
+    /** Whether to mark the field as touched. Default: false. */
+    touched?: boolean;
+};
+export type FormState = {
+    errors: Readonly<Record<string, string> & {
+        [FORM_ERROR]?: string;
+    }>;
+    isDirty: boolean;
+    /** `true` while an async `defaultValues` factory is resolving. */
+    isLoading: boolean;
+    isSubmitting: boolean;
+    isTouched: boolean;
+    isValid: boolean;
+    isValidating: boolean;
+    submitCount: number;
+    /**
+     * Field names that are currently touched, as full dot-notation paths.
+     * On a scoped form these are still full paths (e.g. `"address.city"`, not `"city"`).
+     * Prefer calling `scopedForm.validate()` to run scoped validation rather than
+     * passing `state.touchedFields` directly — scoped `validate(fields[])` expects relative paths.
+     */
+    touchedFields: readonly string[];
+    /** Field names that currently have an active async validation run. Useful for per-field loading indicators. */
+    validatingFields: readonly string[];
+};
+export type SubscribeOptions = {
+    /** Call the listener immediately with the current state on subscription. Default: false. */
+    sync?: boolean;
+};
+/** Shared field key for root-level / form-level validation errors. */
+export declare const FORM_ERROR: "_form";
+export type ValidateResult = {
+    errors: Readonly<Record<string, string>>;
+    valid: boolean;
+};
+export type SubmitResult<TResult = void> = {
+    ok: true;
+    value: TResult;
+} | {
+    errors: Record<string, string>;
+    ok: false;
+    type: 'validation';
+};
+/**
+ * Recursively makes all properties optional.
+ * Used by `form.patch()` to accept partial nested updates.
+ */
+export type DeepPartial<T> = T extends Record<string, unknown> ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+/**
+ * Recursively extracts all dot-notation leaf keys from a values shape.
+ * Depth-limited to 5: TypeScript compilation time grows non-linearly beyond this point.
+ */
+export type FlatKeyOf<T extends Record<string, unknown>, P extends string = '', D extends readonly 0[] = []> = D['length'] extends 5 ? string : {
+    [K in keyof T & string]: T[K] extends unknown[] | File | Blob | Date ? P extends '' ? K : `${P}.${K}` : T[K] extends Record<string, unknown> ? FlatKeyOf<T[K] & Record<string, unknown>, P extends '' ? K : `${P}.${K}`, [...D, 0]> : P extends '' ? K : `${P}.${K}`;
+}[keyof T & string];
+/** Resolves the value type at a dot-notation path within a values shape. */
+export type TypeAtPath<T, K extends string> = K extends `${infer Head}.${infer Tail}` ? Head extends keyof T ? T[Head] extends Record<string, unknown> ? TypeAtPath<T[Head], Tail> : unknown : unknown : K extends keyof T ? T[K] : unknown;
+/** Field error keys include field paths plus the reserved `_form` key for root-level issues. */
+export type ErrorKeyOf<TValues extends Record<string, unknown>> = FlatKeyOf<TValues> | typeof FORM_ERROR;
+/**
+ * Structural interface for safeParse-compatible schemas.
+ * Works with `@vielzeug/spell`, Zod, Valibot, and any Standard Schema compliant library.
+ */
+export type SafeParseSchema = {
+    safeParse(data: unknown): {
+        success: true;
+    } | {
+        error: {
+            issues: {
+                message: string;
+                path: (string | number)[];
+            }[];
+        };
+        success: false;
+    };
+};
+/** The type of values accessible at a scoped sub-form prefix. */
+export type ScopedValues<TValues, P extends string> = TypeAtPath<TValues, P> extends Record<string, unknown> ? TypeAtPath<TValues, P> & Record<string, unknown> : Record<string, unknown>;
+/**
+ * The live connection object returned by `form.connect()`.
+ * Getters re-evaluate on every property access — store the object once per field, do not destructure.
+ * Call `dispose()` to cancel any pending debounce timers when the field unmounts.
+ */
+export type ConnectionResult<V = unknown> = {
+    [Symbol.dispose](): void;
+    readonly dirty: boolean;
+    /** Cancels the debounce timer owned by this specific binding. Safe to call multiple times. */
+    dispose(): void;
+    /** `true` after `dispose()` has been called on this binding. */
+    readonly disposed: boolean;
+    readonly error: string | undefined;
+    onBlur(): void;
+    onChange(value: V): void;
+    readonly touched: boolean;
+    readonly value: V;
+};
+/** Per-field or global validation trigger configuration. */
+export type ConnectOptions = {
+    /**
+     * Debounce auto-triggered validation by this many milliseconds.
+     * Each `connect()` call owns its own timer — cancelling one binding does not affect others.
+     * Default: 0.
+     */
+    debounce?: number;
+    /** Auto-mark the field as touched when it loses focus. Default: false. */
+    touchOnBlur?: boolean;
+    /** Validate the field automatically when it loses focus. Default: false. */
+    validateOnBlur?: boolean;
+    /** Validate the field automatically after each value change. Default: false. */
+    validateOnChange?: boolean;
+    /** Validate on change only after the field has been touched at least once. */
+    validateOnTouch?: boolean;
+};
+type ElementOf<T> = T extends readonly (infer E)[] ? E : unknown;
+export type ArrayField<T = unknown> = {
+    append(value: T): void;
+    insert(index: number, value: T): void;
+    move(from: number, to: number): void;
+    prepend(value: T): void;
+    remove(index: number): void;
+    replace(index: number, value: T): void;
+    swap(a: number, b: number): void;
+};
+export type FieldState<V = unknown> = {
+    dirty: boolean;
+    error: string | undefined;
+    /** `true` when `error` is not `undefined`. Convenience alias for `error !== undefined`. */
+    hasError: boolean;
+    touched: boolean;
+    value: V;
+};
+/**
+ * Options for registering a dynamic field. Both properties are optional;
+ * omitting `defaultValue` leaves the field uninitialized and omitting `validator`
+ * skips field-level validation.
+ */
+export type RegisterFieldOptions<V = unknown> = {
+    /** Initial value. Also becomes the baseline, so the field starts clean. */
+    defaultValue?: V;
+    /** Field-level validator to attach. */
+    validator?: FieldValidator<V>;
+};
+/**
+ * A complete snapshot of form state that can be restored via `form.restore()`.
+ * `store` and `baseline` keys are the flattened dot-notation paths used internally.
+ * Typed with `TValues` for nominal clarity — structurally both are `Record<string, unknown>`.
+ */
+export type FormSnapshot<TValues extends Record<string, unknown> = Record<string, unknown>> = {
+    readonly baseline: Partial<Record<FlatKeyOf<TValues>, unknown>>;
+    readonly dirty: readonly string[];
+    readonly errors: Readonly<Record<string, string>>;
+    readonly store: Partial<Record<FlatKeyOf<TValues>, unknown>>;
+    readonly submitCount: number;
+    readonly touched: readonly string[];
+};
+export type FormOptions<TValues extends Record<string, unknown> = Record<string, unknown>> = {
+    /**
+     * Default connect behavior applied when `connect(name, config)` omits specific options.
+     * Use `ValidationModes` presets for common strategies:
+     * - `ValidationModes.onSubmit` (default) — validates only on submit, no touch-on-blur
+     * - `ValidationModes.onBlur` — validates each field on blur
+     * - `ValidationModes.onChange` — validates each field on every change
+     * - `ValidationModes.onTouched` — validates on blur first, then on every change once touched
+     */
+    connect?: ConnectOptions;
+    /**
+     * Initial form values. May be a static object or an async factory function.
+     * While a factory is pending, `form.isLoading` is `true` and the form is read-only.
+     */
+    defaultValues?: {
+        [K in keyof TValues]: TValues[K];
+    } | (() => Promise<{
+        [K in keyof TValues]: TValues[K];
+    }>);
+    /**
+     * Called when an async `defaultValues` factory rejects.
+     * Use to show an error UI or retry logic. In development, a warning is also emitted via `console.warn`.
+     */
+    onLoadError?: (error: unknown) => void;
+    /**
+     * Form-level validator. Accepts either:
+     * - A `FormValidator` function
+     * - Any `safeParse`-compatible schema (auto-detected, works with `@vielzeug/spell`, Zod, Valibot)
+     */
+    validator?: FormValidator<TValues> | SafeParseSchema;
+    /** Field-level validators keyed by field name or dot-notation path. */
+    validators?: Partial<Record<FlatKeyOf<TValues>, FieldValidator>>;
+};
+/**
+ * Named presets for common validation trigger strategies.
+ * Pass to `createForm({ connect: ValidationModes.onBlur })`.
+ *
+ * - `onSubmit` — no automatic validation or touch. Clean until the user submits.
+ * - `onBlur` — validates and marks touched on blur.
+ * - `onChange` — validates on every keystroke (marks touched on blur).
+ * - `onTouched` — validates on blur first, then on every change once touched.
+ */
+export declare const ValidationModes: {
+    readonly onBlur: {
+        readonly touchOnBlur: true;
+        readonly validateOnBlur: true;
+    };
+    readonly onChange: {
+        readonly touchOnBlur: true;
+        readonly validateOnChange: true;
+    };
+    readonly onSubmit: {};
+    readonly onTouched: {
+        readonly touchOnBlur: true;
+        readonly validateOnBlur: true;
+        readonly validateOnTouch: true;
+    };
+};
+export interface Form<TValues extends Record<string, unknown> = Record<string, unknown>> {
+    /** Returns a cached typed `ArrayField` helper for mutating array-valued fields. */
+    array<K extends FlatKeyOf<TValues>>(name: K): ArrayField<ElementOf<TypeAtPath<TValues, K>>>;
+    batch(fn: () => void): void;
+    /** Clear a single field error. No-op if the field has no error. */
+    clearError(name: ErrorKeyOf<TValues>): void;
+    /**
+     * Returns a live connection object for a field (DOM event handlers + live getters).
+     * Each call to `connect()` creates a new object with its own debounce timer.
+     * Call `binding.dispose()` on unmount to cancel any pending debounce timer.
+     * Do not destructure: getters re-evaluate on every property access.
+     */
+    connect<K extends FlatKeyOf<TValues>>(name: K, config?: ConnectOptions): ConnectionResult<TypeAtPath<TValues, K>>;
+    dispose(): void;
+    /** Aborted when `dispose()` is called. Use to cancel async work tied to this form's lifetime. */
+    readonly disposalSignal: AbortSignal;
+    readonly disposed: boolean;
+    field<K extends FlatKeyOf<TValues>>(name: K): FieldState<TypeAtPath<TValues, K>>;
+    get<K extends FlatKeyOf<TValues>>(name: K): TypeAtPath<TValues, K>;
+    /** `true` while an async `defaultValues` factory is resolving. Mirrors `state.isLoading`. */
+    readonly isLoading: boolean;
+    /** `true` while a `submit()` call is in progress. Mirrors `state.isSubmitting`. */
+    readonly isSubmitting: boolean;
+    /**
+     * Merge a partial server response into the form: updates both the store and the baseline
+     * for each provided field, marking them clean. Fields not included in `partial` are untouched.
+     */
+    patch(partial: DeepPartial<TValues>): void;
+    /**
+     * Field-lifecycle namespace — use to dynamically register/remove fields and manage validators.
+     *
+     * @example
+     * const unsub = form.fields.register('email', { defaultValue: '', validator: required });
+     * form.fields.setValidator('email', (v) => v ? undefined : 'Required');
+     * form.fields.remove('email');
+     */
+    fields: {
+        /**
+         * Enumerate all currently-known field paths: the deduplicated union of populated store
+         * keys and keys with a registered validator (the same definition `touchAll()` uses).
+         * On a scoped form, paths are relative to the scope's prefix — matching `scope.state`'s
+         * relative-path convention, not `state.touchedFields`'s absolute-path convention.
+         */
+        list(): readonly string[];
+        /**
+         * Declare a dynamic field with an optional default value and validator.
+         * If the field does not yet exist in the store, `defaultValue` is written to both the
+         * store and the baseline so the field starts clean (not dirty).
+         * Returns an **unregister** callback that calls `fields.remove()` on the same field.
+         */
+        register<K extends FlatKeyOf<TValues>>(name: K, options?: RegisterFieldOptions<TypeAtPath<TValues, K>>): Unsubscribe;
+        /** Remove a field entirely: drops value, dirty, touched, error, and any registered validator. */
+        remove(name: FlatKeyOf<TValues>): void;
+        /**
+         * Add, replace, or remove a field validator.
+         * Removing a validator (passing `undefined`) also immediately clears any existing error for that field.
+         */
+        setValidator(name: FlatKeyOf<TValues>, validator?: FieldValidator): void;
+    };
+    /** Replace values and baseline in one operation. Aborts any in-flight validation. */
+    replace(newValues: TValues): void;
+    /** Restore values from the current baseline and clear errors/touched/dirty. Aborts any in-flight validation. */
+    reset(): void;
+    resetField(name: FlatKeyOf<TValues>): void;
+    /** Replace the entire error map. Use `undefined` values to omit entries. */
+    resetErrors(errors?: Partial<Record<ErrorKeyOf<TValues>, string | undefined>>): void;
+    /**
+     * Returns a scoped sub-form whose field paths are relative to `prefix`.
+     * `scopedForm.get('city')` is equivalent to `form.get('${prefix}.city')`.
+     * The scoped form shares state and lifecycle with the parent — `dispose()` on a scoped
+     * form is a no-op; call `parentForm.dispose()` to tear down the whole form.
+     *
+     * Results are memoized — calling `scope(prefix)` multiple times with the same prefix
+     * returns the same object. Safe to call on every render.
+     *
+     * **`state`** returns a scoped projection: `errors`, `touchedFields`, `validatingFields`,
+     * `isValid`, `isDirty`, and `isTouched` reflect only fields within this prefix.
+     * `isSubmitting`, `isLoading`, `isValidating`, and `submitCount` reflect the full form.
+     */
+    scope<P extends FlatKeyOf<TValues>>(prefix: P): Form<ScopedValues<TValues, P>>;
+    set<K extends FlatKeyOf<TValues>>(name: K, value: TypeAtPath<TValues, K>, options?: SetOptions): void;
+    /** Set a field error. */
+    setError(name: ErrorKeyOf<TValues>, message: string): void;
+    /**
+     * Capture the complete form state into a snapshot that can be passed to `restore()`.
+     * Useful for undo/redo, draft saving, and "discard changes" flows.
+     */
+    snapshot(): FormSnapshot<TValues>;
+    /**
+     * Restore the form to a previously captured snapshot. Replaces all state:
+     * values, baseline, errors, touched, dirty, and submitCount.
+     * Aborts any in-flight validation.
+     */
+    restore(snapshot: FormSnapshot<TValues>): void;
+    readonly state: FormState;
+    submit<TResult = void>(handler: (values: TValues) => MaybePromise<TResult>): Promise<SubmitResult<TResult>>;
+    /**
+     * Like `submit()` but throws a `ForgeValidationError` when validation fails instead of returning
+     * `{ ok: false, ... }`. Use when you prefer a throw-based control flow.
+     *
+     * @throws {ForgeValidationError} when validation fails.
+     * @throws {Error} when `submit()` is already in progress.
+     */
+    submitOrThrow<TResult = void>(handler: (values: TValues) => MaybePromise<TResult>): Promise<TResult>;
+    subscribe(listener: (state: FormState) => void, options?: SubscribeOptions): Unsubscribe;
+    /**
+     * Subscribe to form state changes filtered to this scope's prefix.
+     * `errors`, `touchedFields`, and `validatingFields` are remapped to relative paths;
+     * all other state flags reflect the full form.
+     * The listener fires only when the scoped projection changes — unrelated field mutations
+     * outside this prefix are suppressed.
+     * On a root form, behaves identically to `subscribe` — no prefix filtering is applied.
+     */
+    subscribeScoped(listener: (state: FormState) => void, options?: SubscribeOptions): Unsubscribe;
+    subscribeField<K extends FlatKeyOf<TValues>>(name: K, listener: (state: FieldState<TypeAtPath<TValues, K>>) => void, options?: SubscribeOptions): Unsubscribe;
+    /**
+     * Iterate over form state changes via `for await`.
+     * Yields the current state immediately, then once per mutation until the iterator
+     * is returned or the form is disposed.
+     *
+     * @example
+     * for await (const state of form) {
+     *   if (state.isSubmitting) showSpinner();
+     * }
+     */
+    [Symbol.asyncIterator](): AsyncIterableIterator<FormState>;
+    /** Delegates to `dispose()`. Enables `using` declarations. */
+    [Symbol.dispose](): void;
+    /** Mark a field as touched. */
+    touch(name: FlatKeyOf<TValues>): void;
+    /** Mark all known fields (store + validators) as touched. */
+    touchAll(): void;
+    /** Mark a field as untouched. No-op if the field is not currently touched. */
+    untouch(name: FlatKeyOf<TValues>): void;
+    /** Mark all fields as untouched. */
+    untouchAll(): void;
+    /**
+     * Validate all registered field validators and the optional form validator.
+     *
+     * On a scoped form: validates only the fields within the scope and does not run the
+     * form-level validator. Errors and `valid` reflect only scoped fields.
+     */
+    validate(signal?: AbortSignal): Promise<ValidateResult>;
+    /**
+     * Validate a single named field. Preserves other fields' errors. Does not run the form-level validator.
+     * Returns a `ValidateResult` scoped to that field — `errors` contains at most one entry.
+     */
+    validate(name: FlatKeyOf<TValues>, signal?: AbortSignal): Promise<ValidateResult>;
+    /**
+     * Validate a specific set of fields. Preserves other fields' errors. Does not run the form-level validator.
+     * Returns a `ValidateResult` scoped to the requested fields.
+     */
+    validate(fields: FlatKeyOf<TValues>[], signal?: AbortSignal): Promise<ValidateResult>;
+    /**
+     * Streaming validation — yields each field result as soon as its validator resolves.
+     * The final item in the stream is the form-level validator result (field: '_form'), if configured.
+     *
+     * @example
+     * for await (const result of form.validateStream()) {
+     *   console.log(result.field, result.error ?? 'ok');
+     * }
+     */
+    validateStream(signal?: AbortSignal): AsyncIterableIterator<{
+        error: string | undefined;
+        field: string;
+    }>;
+    values(): TValues;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,21 @@
+//#region src/types.ts
+var e = "_form", t = {
+	onBlur: {
+		touchOnBlur: !0,
+		validateOnBlur: !0
+	},
+	onChange: {
+		touchOnBlur: !0,
+		validateOnChange: !0
+	},
+	onSubmit: {},
+	onTouched: {
+		touchOnBlur: !0,
+		validateOnBlur: !0,
+		validateOnTouch: !0
+	}
+};
+//#endregion
+export { e as FORM_ERROR, t as ValidationModes };
+
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","names":[],"sources":["../src/types.ts"],"sourcesContent":["/** A callback to remove a subscription. */\nexport type Unsubscribe = () => void;\n\nexport type MaybePromise<T> = T | PromiseLike<T>;\n\nexport type FieldValidator<V = unknown> = (value: V, signal?: AbortSignal) => MaybePromise<string | undefined>;\n\nexport type FormValidator<TValues extends Record<string, unknown> = Record<string, unknown>> = (\n  values: TValues,\n  signal?: AbortSignal,\n) => MaybePromise<Partial<Record<ErrorKeyOf<TValues>, string>> | undefined>;\n\nexport type SetOptions = {\n  /** Whether to mark the field as touched. Default: false. */\n  touched?: boolean;\n};\n\nexport type FormState = {\n  errors: Readonly<Record<string, string> & { [FORM_ERROR]?: string }>;\n  isDirty: boolean;\n  /** `true` while an async `defaultValues` factory is resolving. */\n  isLoading: boolean;\n  isSubmitting: boolean;\n  isTouched: boolean;\n  isValid: boolean;\n  isValidating: boolean;\n  submitCount: number;\n  /**\n   * Field names that are currently touched, as full dot-notation paths.\n   * On a scoped form these are still full paths (e.g. `\"address.city\"`, not `\"city\"`).\n   * Prefer calling `scopedForm.validate()` to run scoped validation rather than\n   * passing `state.touchedFields` directly — scoped `validate(fields[])` expects relative paths.\n   */\n  touchedFields: readonly string[];\n  /** Field names that currently have an active async validation run. Useful for per-field loading indicators. */\n  validatingFields: readonly string[];\n};\n\nexport type SubscribeOptions = {\n  /** Call the listener immediately with the current state on subscription. Default: false. */\n  sync?: boolean;\n};\n\n/** Shared field key for root-level / form-level validation errors. */\nexport const FORM_ERROR = '_form' as const;\n\nexport type ValidateResult = {\n  errors: Readonly<Record<string, string>>;\n  valid: boolean;\n};\n\nexport type SubmitResult<TResult = void> =\n  { ok: true; value: TResult } | { errors: Record<string, string>; ok: false; type: 'validation' };\n\n/* -------------------- Utility Types -------------------- */\n\n/**\n * Recursively makes all properties optional.\n * Used by `form.patch()` to accept partial nested updates.\n */\nexport type DeepPartial<T> = T extends Record<string, unknown> ? { [K in keyof T]?: DeepPartial<T[K]> } : T;\n\n/**\n * Recursively extracts all dot-notation leaf keys from a values shape.\n * Depth-limited to 5: TypeScript compilation time grows non-linearly beyond this point.\n */\nexport type FlatKeyOf<\n  T extends Record<string, unknown>,\n  P extends string = '',\n  D extends readonly 0[] = [],\n> = D['length'] extends 5\n  ? string\n  : {\n      [K in keyof T & string]: T[K] extends unknown[] | File | Blob | Date\n        ? P extends ''\n          ? K\n          : `${P}.${K}`\n        : T[K] extends Record<string, unknown>\n          ? FlatKeyOf<T[K] & Record<string, unknown>, P extends '' ? K : `${P}.${K}`, [...D, 0]>\n          : P extends ''\n            ? K\n            : `${P}.${K}`;\n    }[keyof T & string];\n\n/** Resolves the value type at a dot-notation path within a values shape. */\nexport type TypeAtPath<T, K extends string> = K extends `${infer Head}.${infer Tail}`\n  ? Head extends keyof T\n    ? T[Head] extends Record<string, unknown>\n      ? TypeAtPath<T[Head], Tail>\n      : unknown\n    : unknown\n  : K extends keyof T\n    ? T[K]\n    : unknown;\n\n/** Field error keys include field paths plus the reserved `_form` key for root-level issues. */\nexport type ErrorKeyOf<TValues extends Record<string, unknown>> = FlatKeyOf<TValues> | typeof FORM_ERROR;\n\n/**\n * Structural interface for safeParse-compatible schemas.\n * Works with `@vielzeug/spell`, Zod, Valibot, and any Standard Schema compliant library.\n */\nexport type SafeParseSchema = {\n  safeParse(\n    data: unknown,\n  ): { success: true } | { error: { issues: { message: string; path: (string | number)[] }[] }; success: false };\n};\n\n/** The type of values accessible at a scoped sub-form prefix. */\nexport type ScopedValues<TValues, P extends string> =\n  TypeAtPath<TValues, P> extends Record<string, unknown>\n    ? TypeAtPath<TValues, P> & Record<string, unknown>\n    : Record<string, unknown>;\n\n/**\n * The live connection object returned by `form.connect()`.\n * Getters re-evaluate on every property access — store the object once per field, do not destructure.\n * Call `dispose()` to cancel any pending debounce timers when the field unmounts.\n */\nexport type ConnectionResult<V = unknown> = {\n  [Symbol.dispose](): void;\n  readonly dirty: boolean;\n  /** Cancels the debounce timer owned by this specific binding. Safe to call multiple times. */\n  dispose(): void;\n  /** `true` after `dispose()` has been called on this binding. */\n  readonly disposed: boolean;\n  readonly error: string | undefined;\n  onBlur(): void;\n  onChange(value: V): void;\n  readonly touched: boolean;\n  readonly value: V;\n};\n\n/** Per-field or global validation trigger configuration. */\nexport type ConnectOptions = {\n  /**\n   * Debounce auto-triggered validation by this many milliseconds.\n   * Each `connect()` call owns its own timer — cancelling one binding does not affect others.\n   * Default: 0.\n   */\n  debounce?: number;\n  /** Auto-mark the field as touched when it loses focus. Default: false. */\n  touchOnBlur?: boolean;\n  /** Validate the field automatically when it loses focus. Default: false. */\n  validateOnBlur?: boolean;\n  /** Validate the field automatically after each value change. Default: false. */\n  validateOnChange?: boolean;\n  /** Validate on change only after the field has been touched at least once. */\n  validateOnTouch?: boolean;\n};\n\n// Resolves the element type of an array, or `unknown` for non-arrays.\ntype ElementOf<T> = T extends readonly (infer E)[] ? E : unknown;\n\nexport type ArrayField<T = unknown> = {\n  append(value: T): void;\n  insert(index: number, value: T): void;\n  move(from: number, to: number): void;\n  prepend(value: T): void;\n  remove(index: number): void;\n  replace(index: number, value: T): void;\n  swap(a: number, b: number): void;\n};\n\nexport type FieldState<V = unknown> = {\n  dirty: boolean;\n  error: string | undefined;\n  /** `true` when `error` is not `undefined`. Convenience alias for `error !== undefined`. */\n  hasError: boolean;\n  touched: boolean;\n  value: V;\n};\n\n/**\n * Options for registering a dynamic field. Both properties are optional;\n * omitting `defaultValue` leaves the field uninitialized and omitting `validator`\n * skips field-level validation.\n */\nexport type RegisterFieldOptions<V = unknown> = {\n  /** Initial value. Also becomes the baseline, so the field starts clean. */\n  defaultValue?: V;\n  /** Field-level validator to attach. */\n  validator?: FieldValidator<V>;\n};\n\n/**\n * A complete snapshot of form state that can be restored via `form.restore()`.\n * `store` and `baseline` keys are the flattened dot-notation paths used internally.\n * Typed with `TValues` for nominal clarity — structurally both are `Record<string, unknown>`.\n */\nexport type FormSnapshot<TValues extends Record<string, unknown> = Record<string, unknown>> = {\n  readonly baseline: Partial<Record<FlatKeyOf<TValues>, unknown>>;\n  readonly dirty: readonly string[];\n  readonly errors: Readonly<Record<string, string>>;\n  readonly store: Partial<Record<FlatKeyOf<TValues>, unknown>>;\n  readonly submitCount: number;\n  readonly touched: readonly string[];\n};\n\nexport type FormOptions<TValues extends Record<string, unknown> = Record<string, unknown>> = {\n  /**\n   * Default connect behavior applied when `connect(name, config)` omits specific options.\n   * Use `ValidationModes` presets for common strategies:\n   * - `ValidationModes.onSubmit` (default) — validates only on submit, no touch-on-blur\n   * - `ValidationModes.onBlur` — validates each field on blur\n   * - `ValidationModes.onChange` — validates each field on every change\n   * - `ValidationModes.onTouched` — validates on blur first, then on every change once touched\n   */\n  connect?: ConnectOptions;\n  /**\n   * Initial form values. May be a static object or an async factory function.\n   * While a factory is pending, `form.isLoading` is `true` and the form is read-only.\n   */\n  defaultValues?: { [K in keyof TValues]: TValues[K] } | (() => Promise<{ [K in keyof TValues]: TValues[K] }>);\n  /**\n   * Called when an async `defaultValues` factory rejects.\n   * Use to show an error UI or retry logic. In development, a warning is also emitted via `console.warn`.\n   */\n  onLoadError?: (error: unknown) => void;\n  /**\n   * Form-level validator. Accepts either:\n   * - A `FormValidator` function\n   * - Any `safeParse`-compatible schema (auto-detected, works with `@vielzeug/spell`, Zod, Valibot)\n   */\n  validator?: FormValidator<TValues> | SafeParseSchema;\n  /** Field-level validators keyed by field name or dot-notation path. */\n  validators?: Partial<Record<FlatKeyOf<TValues>, FieldValidator>>;\n};\n\n/**\n * Named presets for common validation trigger strategies.\n * Pass to `createForm({ connect: ValidationModes.onBlur })`.\n *\n * - `onSubmit` — no automatic validation or touch. Clean until the user submits.\n * - `onBlur` — validates and marks touched on blur.\n * - `onChange` — validates on every keystroke (marks touched on blur).\n * - `onTouched` — validates on blur first, then on every change once touched.\n */\nexport const ValidationModes = {\n  onBlur: { touchOnBlur: true, validateOnBlur: true },\n  onChange: { touchOnBlur: true, validateOnChange: true },\n  onSubmit: {},\n  onTouched: { touchOnBlur: true, validateOnBlur: true, validateOnTouch: true },\n} as const satisfies Record<string, ConnectOptions>;\n\nexport interface Form<TValues extends Record<string, unknown> = Record<string, unknown>> {\n  /** Returns a cached typed `ArrayField` helper for mutating array-valued fields. */\n  array<K extends FlatKeyOf<TValues>>(name: K): ArrayField<ElementOf<TypeAtPath<TValues, K>>>;\n  batch(fn: () => void): void;\n  /** Clear a single field error. No-op if the field has no error. */\n  clearError(name: ErrorKeyOf<TValues>): void;\n  /**\n   * Returns a live connection object for a field (DOM event handlers + live getters).\n   * Each call to `connect()` creates a new object with its own debounce timer.\n   * Call `binding.dispose()` on unmount to cancel any pending debounce timer.\n   * Do not destructure: getters re-evaluate on every property access.\n   */\n  connect<K extends FlatKeyOf<TValues>>(name: K, config?: ConnectOptions): ConnectionResult<TypeAtPath<TValues, K>>;\n  dispose(): void;\n  /** Aborted when `dispose()` is called. Use to cancel async work tied to this form's lifetime. */\n  readonly disposalSignal: AbortSignal;\n  readonly disposed: boolean;\n  field<K extends FlatKeyOf<TValues>>(name: K): FieldState<TypeAtPath<TValues, K>>;\n  get<K extends FlatKeyOf<TValues>>(name: K): TypeAtPath<TValues, K>;\n  /** `true` while an async `defaultValues` factory is resolving. Mirrors `state.isLoading`. */\n  readonly isLoading: boolean;\n  /** `true` while a `submit()` call is in progress. Mirrors `state.isSubmitting`. */\n  readonly isSubmitting: boolean;\n  /**\n   * Merge a partial server response into the form: updates both the store and the baseline\n   * for each provided field, marking them clean. Fields not included in `partial` are untouched.\n   */\n  patch(partial: DeepPartial<TValues>): void;\n  /**\n   * Field-lifecycle namespace — use to dynamically register/remove fields and manage validators.\n   *\n   * @example\n   * const unsub = form.fields.register('email', { defaultValue: '', validator: required });\n   * form.fields.setValidator('email', (v) => v ? undefined : 'Required');\n   * form.fields.remove('email');\n   */\n  fields: {\n    /**\n     * Enumerate all currently-known field paths: the deduplicated union of populated store\n     * keys and keys with a registered validator (the same definition `touchAll()` uses).\n     * On a scoped form, paths are relative to the scope's prefix — matching `scope.state`'s\n     * relative-path convention, not `state.touchedFields`'s absolute-path convention.\n     */\n    list(): readonly string[];\n    /**\n     * Declare a dynamic field with an optional default value and validator.\n     * If the field does not yet exist in the store, `defaultValue` is written to both the\n     * store and the baseline so the field starts clean (not dirty).\n     * Returns an **unregister** callback that calls `fields.remove()` on the same field.\n     */\n    register<K extends FlatKeyOf<TValues>>(\n      name: K,\n      options?: RegisterFieldOptions<TypeAtPath<TValues, K>>,\n    ): Unsubscribe;\n    /** Remove a field entirely: drops value, dirty, touched, error, and any registered validator. */\n    remove(name: FlatKeyOf<TValues>): void;\n    /**\n     * Add, replace, or remove a field validator.\n     * Removing a validator (passing `undefined`) also immediately clears any existing error for that field.\n     */\n    setValidator(name: FlatKeyOf<TValues>, validator?: FieldValidator): void;\n  };\n  /** Replace values and baseline in one operation. Aborts any in-flight validation. */\n  replace(newValues: TValues): void;\n  /** Restore values from the current baseline and clear errors/touched/dirty. Aborts any in-flight validation. */\n  reset(): void;\n  resetField(name: FlatKeyOf<TValues>): void;\n  /** Replace the entire error map. Use `undefined` values to omit entries. */\n  resetErrors(errors?: Partial<Record<ErrorKeyOf<TValues>, string | undefined>>): void;\n  /**\n   * Returns a scoped sub-form whose field paths are relative to `prefix`.\n   * `scopedForm.get('city')` is equivalent to `form.get('${prefix}.city')`.\n   * The scoped form shares state and lifecycle with the parent — `dispose()` on a scoped\n   * form is a no-op; call `parentForm.dispose()` to tear down the whole form.\n   *\n   * Results are memoized — calling `scope(prefix)` multiple times with the same prefix\n   * returns the same object. Safe to call on every render.\n   *\n   * **`state`** returns a scoped projection: `errors`, `touchedFields`, `validatingFields`,\n   * `isValid`, `isDirty`, and `isTouched` reflect only fields within this prefix.\n   * `isSubmitting`, `isLoading`, `isValidating`, and `submitCount` reflect the full form.\n   */\n  scope<P extends FlatKeyOf<TValues>>(prefix: P): Form<ScopedValues<TValues, P>>;\n  set<K extends FlatKeyOf<TValues>>(name: K, value: TypeAtPath<TValues, K>, options?: SetOptions): void;\n  /** Set a field error. */\n  setError(name: ErrorKeyOf<TValues>, message: string): void;\n  /**\n   * Capture the complete form state into a snapshot that can be passed to `restore()`.\n   * Useful for undo/redo, draft saving, and \"discard changes\" flows.\n   */\n  snapshot(): FormSnapshot<TValues>;\n  /**\n   * Restore the form to a previously captured snapshot. Replaces all state:\n   * values, baseline, errors, touched, dirty, and submitCount.\n   * Aborts any in-flight validation.\n   */\n  restore(snapshot: FormSnapshot<TValues>): void;\n  readonly state: FormState;\n  submit<TResult = void>(handler: (values: TValues) => MaybePromise<TResult>): Promise<SubmitResult<TResult>>;\n  /**\n   * Like `submit()` but throws a `ForgeValidationError` when validation fails instead of returning\n   * `{ ok: false, ... }`. Use when you prefer a throw-based control flow.\n   *\n   * @throws {ForgeValidationError} when validation fails.\n   * @throws {Error} when `submit()` is already in progress.\n   */\n  submitOrThrow<TResult = void>(handler: (values: TValues) => MaybePromise<TResult>): Promise<TResult>;\n  subscribe(listener: (state: FormState) => void, options?: SubscribeOptions): Unsubscribe;\n  /**\n   * Subscribe to form state changes filtered to this scope's prefix.\n   * `errors`, `touchedFields`, and `validatingFields` are remapped to relative paths;\n   * all other state flags reflect the full form.\n   * The listener fires only when the scoped projection changes — unrelated field mutations\n   * outside this prefix are suppressed.\n   * On a root form, behaves identically to `subscribe` — no prefix filtering is applied.\n   */\n  subscribeScoped(listener: (state: FormState) => void, options?: SubscribeOptions): Unsubscribe;\n  subscribeField<K extends FlatKeyOf<TValues>>(\n    name: K,\n    listener: (state: FieldState<TypeAtPath<TValues, K>>) => void,\n    options?: SubscribeOptions,\n  ): Unsubscribe;\n  /**\n   * Iterate over form state changes via `for await`.\n   * Yields the current state immediately, then once per mutation until the iterator\n   * is returned or the form is disposed.\n   *\n   * @example\n   * for await (const state of form) {\n   *   if (state.isSubmitting) showSpinner();\n   * }\n   */\n  [Symbol.asyncIterator](): AsyncIterableIterator<FormState>;\n  /** Delegates to `dispose()`. Enables `using` declarations. */\n  [Symbol.dispose](): void;\n  /** Mark a field as touched. */\n  touch(name: FlatKeyOf<TValues>): void;\n  /** Mark all known fields (store + validators) as touched. */\n  touchAll(): void;\n  /** Mark a field as untouched. No-op if the field is not currently touched. */\n  untouch(name: FlatKeyOf<TValues>): void;\n  /** Mark all fields as untouched. */\n  untouchAll(): void;\n  /**\n   * Validate all registered field validators and the optional form validator.\n   *\n   * On a scoped form: validates only the fields within the scope and does not run the\n   * form-level validator. Errors and `valid` reflect only scoped fields.\n   */\n  validate(signal?: AbortSignal): Promise<ValidateResult>;\n  /**\n   * Validate a single named field. Preserves other fields' errors. Does not run the form-level validator.\n   * Returns a `ValidateResult` scoped to that field — `errors` contains at most one entry.\n   */\n  validate(name: FlatKeyOf<TValues>, signal?: AbortSignal): Promise<ValidateResult>;\n  /**\n   * Validate a specific set of fields. Preserves other fields' errors. Does not run the form-level validator.\n   * Returns a `ValidateResult` scoped to the requested fields.\n   */\n  validate(fields: FlatKeyOf<TValues>[], signal?: AbortSignal): Promise<ValidateResult>;\n  /**\n   * Streaming validation — yields each field result as soon as its validator resolves.\n   * The final item in the stream is the form-level validator result (field: '_form'), if configured.\n   *\n   * @example\n   * for await (const result of form.validateStream()) {\n   *   console.log(result.field, result.error ?? 'ok');\n   * }\n   */\n  validateStream(signal?: AbortSignal): AsyncIterableIterator<{ error: string | undefined; field: string }>;\n  values(): TValues;\n}\n"],"mappings":";AA4CA,IAAa,IAAa,SAkMb,IAAkB;CAC7B,QAAQ;EAAE,aAAa;EAAM,gBAAgB;CAAK;CAClD,UAAU;EAAE,aAAa;EAAM,kBAAkB;CAAK;CACtD,UAAU,CAAC;CACX,WAAW;EAAE,aAAa;EAAM,gBAAgB;EAAM,iBAAiB;CAAK;AAC9E"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@vielzeug/forge",
+  "version": "1.1.2",
+  "description": "Type-safe form state — field-level validation, submission, dirty tracking, field arrays, and async default values",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./devtools": {
+      "source": "./src/devtools.ts",
+      "types": "./dist/devtools.d.ts",
+      "import": "./dist/devtools.js",
+      "require": "./dist/devtools.cjs"
+    },
+    "./validators": {
+      "source": "./src/adapters/validators.ts",
+      "types": "./dist/adapters/validators.d.ts",
+      "import": "./dist/adapters/validators.js",
+      "require": "./dist/adapters/validators.cjs"
+    }
+  },
+  "scripts": {
+    "build": "vite build && pnpm run build:bundle && pnpm run build:types",
+    "build:types": "tsc -p tsconfig.declarations.json",
+    "fix": "eslint --fix src",
+    "lint": "eslint src",
+    "prepublishOnly": "pnpm run build",
+    "preview": "vite preview",
+    "test": "vitest",
+    "build:bundle": "vite build --config vite.bundle.config.ts"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@vielzeug/arsenal": "workspace:*",
+    "@vielzeug/ripple": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "typescript": "~6.0.3",
+    "vite": "^8.1.3",
+    "vitest": "^4.1.9"
+  }
+}