attaform 0.21.2 → 0.22.0

package/dist/shared/{attaform.ory-3WhV.d.mts → attaform.DvUH4a3o.d.ts}

@@ -1,4 +1,4 @@
-import { ObjectDirective, Ref, ComputedRef } from 'vue';
+import { ObjectDirective, Ref, MaybeRefOrGetter, ComputedRef } from 'vue';
 
 /**
  * Schema-attached field metadata — the shared types used by both Zod
@@ -1540,6 +1540,132 @@ type WriteMeta = {
      * consumer code.
      */
     readonly crossTab?: boolean;
+    /**
+     * When `true`, this write lands normally (storage, validation,
+     * persistence, history) but does NOT notify `form.onChange` handlers.
+     * The side-channel reacts to user edits, not programmatic rebaselines:
+     * `reset()` tags its replacement with this flag, and the public
+     * `setValue(path, value, { silent: true })` option forwards it so a
+     * consumer hydrating the form (loading a saved record into the fields)
+     * can land values without echoing each one back through an autosave
+     * loop. The store's internal taggers and that single consumer-facing
+     * option are the only writers.
+     */
+    readonly silent?: boolean;
+};
+/** Options for a `setValue` write. */
+type SetValueOptions = {
+    /**
+     * When `true`, the write lands normally (storage, validation, persistence,
+     * history) but does NOT notify `form.onChange` handlers. Use it to hydrate
+     * the form (load a saved record into the fields) without echoing every
+     * field back through an autosave loop.
+     */
+    readonly silent?: boolean;
+};
+/**
+ * A source address for `form.onChange` — the subtree(s) a handler reacts to.
+ *
+ * - a dotted path string (`'user.email'`) — one leaf or subtree;
+ * - a list of path strings (`['shipping', 'billing']`) — react to any of
+ *   several paths; the handler fires once per matched path, `ctx.path`
+ *   distinguishing which;
+ * - a getter or ref / computed resolving to either — re-read on each write,
+ *   so the aim can follow a moving target (the active list row). Re-aiming
+ *   is never itself a trigger; only a real write dispatches.
+ *
+ * Omit the source entirely (`form.onChange(handler)`) to react to the whole
+ * form. An empty list (`form.onChange([], handler)`) lists zero paths, so it
+ * never fires — that is a deliberate no-op, NOT a shorthand for the root.
+ */
+type OnChangeSource = MaybeRefOrGetter<string | readonly string[]>;
+/**
+ * Context handed to an `onChange` handler alongside the changed value.
+ *
+ * `onChange` is a pure side-channel: it reacts to value changes and runs
+ * side effects, but never touches the form's own lifecycle. Nothing a
+ * handler does here marks the form dirty, pending, or validating — autosave
+ * status lives in the consumer's own state, validation in `.refine` and
+ * `field.show*`.
+ */
+type OnChangeContext<FormApi = unknown> = {
+    /**
+     * The source path this fire is for, in dotted form (`'user.email'`).
+     * The empty string `''` is the whole form (a root handler). For a
+     * multi-path source, the handler fires once per matched path and `path`
+     * names which one.
+     */
+    readonly path: string;
+    /**
+     * The value at the source path BEFORE this change, seeded at registration.
+     * Accurate for leaf sources. For a container or the whole form, an
+     * in-place leaf edit preserves the container's reference, so `previous`
+     * can be reference-equal to the current value (Vue's deep-watch gotcha) —
+     * snapshot inside the handler if a true container diff is needed.
+     */
+    readonly previous: unknown;
+    /**
+     * Aborted when a newer write to the same source supersedes this run. A
+     * debounced or awaiting handler should bail on `signal.aborted` (or pass
+     * `signal` straight to `fetch`) so superseded work cancels itself.
+     */
+    readonly signal: AbortSignal;
+    /** Retry counter — `0` on the first run, incremented by `onError`'s `retry()`. */
+    readonly attempt: number;
+    /**
+     * The form handle, so a portable `useForm({ onChange })` handler can reach
+     * back into the form (e.g. `ctx.form.validateAsync(ctx.path)` to gate an
+     * autosave on validity). Typed precisely by the `form.onChange` overload.
+     */
+    readonly form: FormApi;
+    /**
+     * The leaf path(s), in dotted form, that actually changed in this
+     * dispatch. For a leaf source this is just `[path]`; for a container or
+     * the whole form it is every changed descendant.
+     */
+    readonly changed: readonly string[];
+};
+/**
+ * Context handed to an `onChange` handler's `onError` callback when the
+ * handler throws or rejects.
+ */
+type OnChangeErrorContext<FormApi = unknown> = {
+    /** The source path this run was for, in dotted form (`''` for the whole form). */
+    readonly path: string;
+    /** The value passed to the handler that failed. */
+    readonly value: unknown;
+    /** The attempt number that failed (`0` on the first run). */
+    readonly attempt: number;
+    /**
+     * Re-run the handler with the same value and `attempt + 1`. A no-op once a
+     * newer write has superseded this run — stale work is never resurrected.
+     * Backoff and a retry cap are the consumer's to impose.
+     */
+    readonly retry: () => void;
+    /** The form handle. Typed precisely by the `form.onChange` overload. */
+    readonly form: FormApi;
+};
+/** A reaction to form value changes. Its return is ignored; throws route to `onError`. */
+type OnChangeHandler<Value = unknown, FormApi = unknown> = (value: Value, ctx: OnChangeContext<FormApi>) => void | Promise<void>;
+/** Handles a throw / rejection from an `onChange` handler. Must not throw. */
+type OnChangeErrorHandler<FormApi = unknown> = (error: unknown, ctx: OnChangeErrorContext<FormApi>) => void;
+/** Options for `form.onChange`. */
+type OnChangeOptions<FormApi = unknown> = {
+    /**
+     * Called when the handler throws or its promise rejects. Without it, a
+     * failure is swallowed (logged in dev). `onChange` never throws into the
+     * write that triggered it.
+     */
+    readonly onError?: OnChangeErrorHandler<FormApi>;
+};
+/**
+ * The `useForm({ onChange })` option — a whole-form handler registered at
+ * construction, bound to the form's lifetime. Either a bare handler or a
+ * `{ handler, onError }` pair.
+ */
+type OnChangeConfig<Value = unknown, FormApi = unknown> = OnChangeHandler<Value, FormApi> | {
+    readonly handler: OnChangeHandler<Value, FormApi>;
+    readonly onError?: OnChangeErrorHandler<FormApi>;
 };
 /**
  * Undo/redo configuration passed via `useForm({ history })`.
@@ -1825,6 +1951,17 @@ type UseFormConfiguration<Form extends GenericForm, GetValueFormType, Schema ext
      * per blur for `<input v-register.lazy>`).
      */
     debounceMs?: number;
+    /**
+     * A whole-form `onChange` handler, registered at construction and bound to
+     * the form's lifetime. The same side-channel as `form.onChange(handler)`,
+     * but declared in the options bag so it travels with the form (handy for a
+     * `useAutosave`-style composable). Pass a handler, or `{ handler, onError }`.
+     *
+     * For path-scoped reactions, call `form.onChange('path', handler)` on the
+     * returned form instead. `onChange` never touches the form's own
+     * lifecycle — keep validation in `.refine` and `field.show*`.
+     */
+    onChange?: OnChangeConfig<Form, UseFormReturnType<Form>>;
     /**
      * Opt-in persistence of the form's draft state. Off by default —
      * with no config, no reads, no writes, no storage code is loaded.
@@ -4285,8 +4422,11 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
          * type at a leaf). Refinement-level mismatches (out-of-enum
          * values, failing format checks, etc.) succeed and surface as
          * field errors instead.
+         *
+         * Pass `{ silent: true }` to land the write without notifying
+         * `form.onChange` handlers (e.g. hydrating a saved record).
          */
-        <Value extends SetValuePayload<DefaultValuesShape<Form>, WriteShape<Form>>>(value: Value): boolean;
+        <Value extends SetValuePayload<DefaultValuesShape<Form>, WriteShape<Form>>>(value: Value, options?: SetValueOptions): boolean;
         /**
          * Write at a specific path. Pass a value or a callback receiving
          * the previous value at that path.
@@ -4304,14 +4444,49 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
          * it blank (storage holds the slim default; UI displays
          * empty; submit raises "No value supplied" for required schemas).
          */
-        <Path extends FlatPath<Form>, Value extends PathSetValuePayload<NestedType<Form, Path>>>(path: Path, value: Value): boolean;
+        <Path extends FlatPath<Form>, Value extends PathSetValuePayload<NestedType<Form, Path>>>(path: Path, value: Value, options?: SetValueOptions): boolean;
         /**
          * Tuple-segment form. Equivalent to the dotted-string overload —
          * useful when paths are built from variables or arrays:
          * `form.setValue([prefix, 'line1'], 'value')`. The resolved leaf
          * type is exact, matching the dotted-string form.
          */
-        <const S extends ReadonlyArray<string | number>, Value extends PathSetValuePayload<NestedType<Form, JoinSegments<S>>>>(segments: S & ([JoinSegments<S>] extends [FlatPath<Form>] ? unknown : never), value: Value): boolean;
+        <const S extends ReadonlyArray<string | number>, Value extends PathSetValuePayload<NestedType<Form, JoinSegments<S>>>>(segments: S & ([JoinSegments<S>] extends [FlatPath<Form>] ? unknown : never), value: Value, options?: SetValueOptions): boolean;
+    };
+    /**
+     * Subscribe to form value changes — the side-channel autosave is built on.
+     * Three call forms:
+     *
+     * - `form.onChange(handler, options?)` — react to the whole form.
+     * - `form.onChange('user.email', handler, options?)` — react to one path;
+     *   `value` is that path's value.
+     * - `form.onChange(source, handler, options?)` — react to a list of paths,
+     *   or a getter / ref resolving to a path or list (re-read on each write,
+     *   so the aim can follow a moving target like the active list row).
+     *
+     * The handler runs AFTER the value lands. Its return is ignored, and a
+     * throw or rejection routes to `options.onError`, never into the write that
+     * triggered it. Returns an idempotent `stop()`; called inside a component's
+     * setup it also stops automatically on unmount.
+     *
+     * `onChange` is a pure side-channel: nothing it does marks the form dirty,
+     * pending, or validating. Keep validation feedback in `.refine` and
+     * `field.show*`, and track autosave status in your own state.
+     *
+     * ```ts
+     * form.onChange('user.email', async (email, ctx) => {
+     *   const verdict = await ctx.form.validateAsync(ctx.path)
+     *   if (verdict.success) await api.save({ email }, { signal: ctx.signal })
+     * }, { onError: (error, ctx) => ctx.retry() })
+     * ```
+     */
+    onChange: {
+        /** React to the whole form. `value` is the current form. */
+        (handler: OnChangeHandler<ReadForm, UseFormReturnType<Form, GetValueFormType, ReadForm, K>>, options?: OnChangeOptions<UseFormReturnType<Form, GetValueFormType, ReadForm, K>>): () => void;
+        /** React to one path. `value` is that path's value. */
+        <P extends FlatPath<Form>>(source: P, handler: OnChangeHandler<NestedType<Form, P>, UseFormReturnType<Form, GetValueFormType, ReadForm, K>>, options?: OnChangeOptions<UseFormReturnType<Form, GetValueFormType, ReadForm, K>>): () => void;
+        /** React to a list of paths, or a getter / ref / computed. `value` is unknown. */
+        (source: OnChangeSource, handler: OnChangeHandler<unknown, UseFormReturnType<Form, GetValueFormType, ReadForm, K>>, options?: OnChangeOptions<UseFormReturnType<Form, GetValueFormType, ReadForm, K>>): () => void;
     };
     /**
      * Reactive validation status. Re-runs whenever the form (or the
@@ -4915,5 +5090,5 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
     blankPaths: ComputedRef<BlankPathsView>;
 };
 
-export { ROOT_PATH as a4, ROOT_PATH_KEY as a5, canonicalizePath as as, isPathPrefix as at, isUnset as au, parseDottedPath as av, unset as aw };
-export type { PendingValidationStatus as $, AttaformDefaults as A, FormStorage as B, CoercionEntry as C, DefaultValuesInput as D, ErrorsProxyShape as E, FormKey as F, GenericForm as G, FormStorageKind as H, HandleSubmit as I, HistoryConfig as J, IsTuple as K, IsUnion as L, JoinSegments as M, KeyofUnion as N, LiftedValueShape as O, MetaTrackerValue as P, NestedReadType as Q, RegisterModelDynamicCustomDirective as R, NestedType as S, OnError as T, UseFormConfiguration as U, ValidationError as V, OnInvalidSubmitPolicy as W, OnSubmit as X, PartialFlatPath as Y, Path as Z, PathKey as _, AbstractSchema as a, PersistConfig as a0, PersistConfigOptions as a1, PersistIncludeMode as a2, Primitive as a3, ReactiveValidationStatus as a6, RegisterDirective as a7, RegisterFlatPath as a8, RegisterOptions as a9, RegisterSelectModifier as aa, RegisterTextModifier as ab, RegisterTransform as ac, Segment as ad, SetValueCallback as ae, SetValuePayload as af, SettledValidationStatus as ag, SlimPrimitiveKind as ah, SlimRuntimeOf as ai, SubmitHandler as aj, Unset as ak, ValidateOn as al, ValidateOnConfig as am, ValidationResponse as an, ValidationResponseWithoutValue as ao, ValueOfUnion as ap, WriteMeta as aq, WriteShape as ar, SchemaFactoryOptions as ax, TransformAbortHolder as ay, PersistOptInRegistry as az, UseFormReturnType as b, RegisterValue as c, GetDisplayState as d, ApiErrorEnvelope as e, ApiErrorDetails as f, ApiErrorEntry as g, ArrayItem as h, ArrayPath as i, CoercionRegistry as j, CoercionResult as k, CustomDirectiveRegisterAssignerFn as l, DeepPartial as m, DefaultValuesResponse as n, DefaultValuesShape as o, DisplayCtx as p, DisplayMachine as q, DisplayState as r, FieldMetaPayload as s, FieldState as t, FieldStateMap as u, FieldStateMapEntry as v, FlatPath as w, FormErrorRecord as x, FormErrorsSurface as y, FormMeta as z };
+export { canonicalizePath as aA, isPathPrefix as aB, isUnset as aC, parseDottedPath as aD, unset as aE, ROOT_PATH as ab, ROOT_PATH_KEY as ac };
+export type { OnChangeSource as $, AttaformDefaults as A, FormStorage as B, CoercionEntry as C, DefaultValuesInput as D, ErrorsProxyShape as E, FormKey as F, GenericForm as G, FormStorageKind as H, HandleSubmit as I, HistoryConfig as J, IsTuple as K, IsUnion as L, JoinSegments as M, KeyofUnion as N, LiftedValueShape as O, MetaTrackerValue as P, NestedReadType as Q, RegisterModelDynamicCustomDirective as R, NestedType as S, OnChangeConfig as T, UseFormConfiguration as U, ValidationError as V, OnChangeContext as W, OnChangeErrorContext as X, OnChangeErrorHandler as Y, OnChangeHandler as Z, OnChangeOptions as _, AbstractSchema as a, OnError as a0, OnInvalidSubmitPolicy as a1, OnSubmit as a2, PartialFlatPath as a3, Path as a4, PathKey as a5, PendingValidationStatus as a6, PersistConfig as a7, PersistConfigOptions as a8, PersistIncludeMode as a9, SchemaFactoryOptions as aF, TransformAbortHolder as aG, PersistOptInRegistry as aH, Primitive as aa, ReactiveValidationStatus as ad, RegisterDirective as ae, RegisterFlatPath as af, RegisterOptions as ag, RegisterSelectModifier as ah, RegisterTextModifier as ai, RegisterTransform as aj, Segment as ak, SetValueCallback as al, SetValueOptions as am, SetValuePayload as an, SettledValidationStatus as ao, SlimPrimitiveKind as ap, SlimRuntimeOf as aq, SubmitHandler as ar, Unset as as, ValidateOn as at, ValidateOnConfig as au, ValidationResponse as av, ValidationResponseWithoutValue as aw, ValueOfUnion as ax, WriteMeta as ay, WriteShape as az, UseFormReturnType as b, RegisterValue as c, GetDisplayState as d, ApiErrorEnvelope as e, ApiErrorDetails as f, ApiErrorEntry as g, ArrayItem as h, ArrayPath as i, CoercionRegistry as j, CoercionResult as k, CustomDirectiveRegisterAssignerFn as l, DeepPartial as m, DefaultValuesResponse as n, DefaultValuesShape as o, DisplayCtx as p, DisplayMachine as q, DisplayState as r, FieldMetaPayload as s, FieldState as t, FieldStateMap as u, FieldStateMapEntry as v, FlatPath as w, FormErrorRecord as x, FormErrorsSurface as y, FormMeta as z };

package/dist/shared/{attaform.BoY6RZUl.d.cts → attaform.FN0vaQAg.d.mts}

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { G as GenericForm, w as FlatPath, S as NestedType, F as FormKey, U as UseFormConfiguration, a as AbstractSchema, D as DefaultValuesInput, am as ValidateOnConfig, b as UseFormReturnType } from './attaform.ory-3WhV.cjs';
+import { G as GenericForm, w as FlatPath, S as NestedType, F as FormKey, U as UseFormConfiguration, a as AbstractSchema, D as DefaultValuesInput, au as ValidateOnConfig, b as UseFormReturnType } from './attaform.DvUH4a3o.mjs';
 
 /**
  * The shape `form.values.<key>` returns at runtime.

package/dist/shared/{attaform.BwrowMp2.cjs → attaform.Q3eAD2wD.cjs}

@@ -1,7 +1,7 @@
 'use strict';
 
-const injectWizard = require('./attaform.D2ZuIOCf.cjs');
-const paths = require('./attaform.B5LNzqQh.cjs');
+const injectWizard = require('./attaform.CjMcwV7W.cjs');
+const paths = require('./attaform.01iKS_lz.cjs');
 
 const PATH_SEPARATOR = ".";
 function createAbstractSchema(rootSchema, intro, services, formKey, options) {
@@ -914,4 +914,4 @@ exports.mergeDeep = mergeDeep;
 exports.peelEmbeddedDefault = peelEmbeddedDefault;
 exports.slimPrimitivesWalk = slimPrimitivesWalk;
 exports.walkPathSegments = walkPathSegments;
-//# sourceMappingURL=attaform.BwrowMp2.cjs.map
+//# sourceMappingURL=attaform.Q3eAD2wD.cjs.map