attaform 0.25.0 → 0.27.0

package/dist/shared/{attaform.i_LA3X9o.d.cts → attaform.C3WnCDXz.d.cts}

@@ -137,8 +137,8 @@ declare function canonicalizePath(input: string | Path): {
  * `Path` to address the form value as a whole, and the home for
  * form-level (global) errors: root `.refine()` messages, hydration
  * failures, and `setErrors` entries with no path all live at `[]`. Aggregate
- * reads (`errors()`, `meta.errors`) surface them alongside field
- * errors; `errors([])` returns the global bucket alone.
+ * reads (`errors()`, `errors([])`, `meta.errors`) surface them alongside
+ * field errors; `meta.ownErrors` returns the root bucket alone.
  *
  * The empty SEGMENT tuple `[]` is structurally unconstructible as a
  * field path, so it can never collide with a schema key, unlike the
@@ -2074,14 +2074,15 @@ type OnError = (error: ValidationError[]) => void | Promise<void>;
 type DisplayState = 'idle' | 'pending' | 'error' | 'success';
 /**
  * Keys on `FieldState` layered on FROM the display-state predicate
- * (plus `firstError`, computed alongside them). `Omit`'d from the
- * predicate's arguments so a predicate cannot read its own output and
- * form a cycle — enforced at the type level AND at runtime: the base
- * objects passed in literally lack these keys, so an `as` cast in TS
- * or a vanilla-JS caller still can't reach them. `FieldStateBase` /
- * `FormMetaBase` (field-state-api.ts) omit the same set in lockstep.
+ * (plus `firstError` / `firstOwnError`, computed alongside them).
+ * `Omit`'d from the predicate's arguments so a predicate cannot read
+ * its own output and form a cycle — enforced at the type level AND at
+ * runtime: the base objects passed in literally lack these keys, so an
+ * `as` cast in TS or a vanilla-JS caller still can't reach them.
+ * `FieldStateBase` / `FormMetaBase` (field-state-api.ts) omit the same
+ * set in lockstep.
  */
-type FieldStateDerivedKey = 'displayState' | 'showErrors' | 'showPending' | 'showSuccess' | 'showIdle' | 'firstError';
+type FieldStateDerivedKey = 'displayState' | 'showErrors' | 'showPending' | 'showSuccess' | 'showIdle' | 'firstError' | 'firstOwnError';
 /**
  * One step of the display state machine: the verdict the field should
  * render right now (`display`, projected to `displayState` and the
@@ -2163,12 +2164,13 @@ type GetDisplayState = (prev: DisplayMachine, ctx: DisplayCtx) => DisplayMachine
  * it to a `<form>`:
  *
  * ```vue
- * <form @submit.prevent="onSubmit">…</form>
+ * <form @submit="onSubmit">…</form>
  * ```
  *
- * It optionally accepts the originating `Event` so it can sit on
- * `@submit` directly (without `.prevent` if you want to call
- * `event.preventDefault()` yourself).
+ * It accepts the originating `Event` and calls `event.preventDefault()`
+ * itself, so bind it with `@submit`, not `@submit.prevent` (the
+ * modifier would only prevent the default a second time). Called
+ * imperatively with no event, the `preventDefault` step is skipped.
  */
 type SubmitHandler = (event?: Event) => Promise<void>;
 /**
@@ -3114,7 +3116,40 @@ type FieldState<Value = unknown> = {
      */
     readonly elements: readonly HTMLElement[];
     readonly updatedAt: string | null;
+    /**
+     * Every `ValidationError` in this path's SUBTREE: the node's own
+     * bucket plus every descendant's, sorted by schema-declaration order.
+     * On a leaf (no descendants) this equals `ownErrors`. On a container
+     * it rolls up the whole fieldset, so a parent's `errors` is non-empty
+     * whenever any child is invalid.
+     *
+     * For the errors pinned at THIS path alone (a container's own
+     * cross-field `.refine()`, or `setErrors` at this path), read
+     * `ownErrors`.
+     */
     readonly errors: readonly ValidationError[];
+    /**
+     * Every `ValidationError` at THIS exact path's own bucket, excluding
+     * descendants: schema errors, blank-required errors, and `setErrors`
+     * pinned here, in `schema`, `blank`, `user` order. The exact-path
+     * counterpart to the subtree-scoped `errors`.
+     *
+     * On a leaf this is the same array as `errors` (a leaf has no
+     * descendants). On a container it holds only the container's OWN
+     * errors, a cross-field `.refine()` on the fieldset or a path-less
+     * `setErrors` at this node, without dragging in any child error:
+     *
+     * ```vue
+     * <p v-if="form.fields.address.firstOwnError">
+     *   {{ form.fields.address.firstOwnError.message }}
+     * </p>
+     * ```
+     *
+     * On `form.meta` this is the root `[]` bucket: form-level errors from
+     * a root `.refine()` or a path-less `setErrors`. `form.meta.ownErrors`
+     * (with `firstOwnError`) is the banner accessor for those.
+     */
+    readonly ownErrors: readonly ValidationError[];
     /**
      * `true` while a per-field validation run is in flight at this path.
      * Reflects field-level debounced runs (`validate-on-change`) and
@@ -3235,9 +3270,28 @@ type FieldState<Value = unknown> = {
      * decides when to render it.
      *
      * On container paths, the first error in the aggregated subtree
-     * (descendants sorted by `pathOrdinal`).
+     * (descendants sorted by `pathOrdinal`). For the container's OWN
+     * first error only, read `firstOwnError`.
      */
     readonly firstError: ValidationError | undefined;
+    /**
+     * The first `ValidationError` in `ownErrors` (this exact path's own
+     * bucket), or `undefined` when that bucket is empty. Equivalent to
+     * `ownErrors[0]`, the exact-path counterpart to `firstError`.
+     *
+     * On a leaf this equals `firstError`. On a container it is the
+     * container's own cross-field error (a fieldset `.refine()`), never a
+     * child's. `form.meta.firstOwnError` is the form-level banner: the
+     * first root `[]` error from a root `.refine()` or a path-less
+     * `setErrors`:
+     *
+     * ```vue
+     * <p v-if="form.meta.firstOwnError" role="alert">
+     *   {{ form.meta.firstOwnError.message }}
+     * </p>
+     * ```
+     */
+    readonly firstOwnError: ValidationError | undefined;
     readonly path: ReadonlyArray<string | number>;
     /**
      * Stable, SSR-safe DOM id for this field, unique across every mount
@@ -3601,11 +3655,13 @@ type FormErrorsSurface<Form> = ErrorsProxyShape<Form> & {
     <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [FlatPath<Form>] ? unknown : never)): readonly ValidationError[];
     (segments: ReadonlyArray<string | number>): readonly ValidationError[];
     /**
-     * No-arg call returns the whole-form error aggregate — same as
-     * `form.meta.errors`: every field error plus the global bucket.
-     * Distinct from `form.errors([])`, which returns ONLY the global
-     * (root) bucket. Always a readonly array; empty when the form has no
-     * errors.
+     * No-arg call returns the whole-form error aggregate, the same as
+     * `form.meta.errors` and `form.errors([])`: every field error plus
+     * the root bucket. `form.errors(path)` is uniform at every depth,
+     * including `[]`, so the root is no exception. For the root bucket
+     * alone (a root `.refine()`, a path-less `setErrors`), read
+     * `form.meta.ownErrors`. Always a readonly array; empty when the form
+     * has no errors.
      */
     (): readonly ValidationError[];
 };
@@ -3732,7 +3788,7 @@ type FormMeta<F = unknown> = FieldState<F> & {
      * of each new submission attempt; stays `null` on success.
      *
      * The submit handler does NOT re-throw — its returned promise always
-     * resolves, so binding it to `@submit.prevent` never manufactures a
+     * resolves, so binding it to `@submit` never manufactures a
      * `window` unhandledrejection. This is the channel for an UNEXPECTED
      * submit failure (a thrown exception or rejected promise), read the
      * same way in templates and after an imperative `await submit()`. An
@@ -3893,10 +3949,11 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * Wraps your submit logic with validation and error routing.
      *
      * ```ts
-     * <form @submit.prevent="form.handleSubmit(
+     * const onSubmit = form.handleSubmit(
      *   (data) => api.signup(data),
      *   (errors) => console.log(errors),
-     * )">
+     * )
+     * // Bind the returned handler: <form @submit="onSubmit">
      * ```
      *
      * `data` is the strictly-typed parsed value — refinements have
@@ -4591,5 +4648,5 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
     blankPaths: ComputedRef<BlankPathsView>;
 };
 
-export { ROOT_PATH as Z, ROOT_PATH_KEY as _, canonicalizePath as am, isPathPrefix as an, isUnset as ao, parseDottedPath as ap, unset as aq };
-export type { ReactiveValidationStatus as $, AttaformDefaults as A, Json as B, CoercionEntry as C, DefaultValuesInput as D, ErrorInput as E, FormKey as F, GenericForm as G, HandleSubmit as H, IsTuple as I, JoinSegments as J, KeyofUnion as K, LiftedValueShape as L, MetaTrackerValue as M, NestedReadType as N, NestedType as O, OnError as P, OnInvalidSubmitPolicy as Q, RegisterModelDynamicCustomDirective as R, OnSubmit as S, PartialFlatPath as T, UseFormConfiguration as U, Path as V, PathKey as W, PendingValidationStatus as X, Primitive as Y, AbstractSchema as a, RegisterDirective as a0, RegisterFlatPath as a1, RegisterOptions as a2, RegisterSelectModifier as a3, RegisterTextModifier as a4, RegisterTransform as a5, Segment as a6, SetValueCallback as a7, SetValuePayload as a8, SettledValidationStatus as a9, SlimPrimitiveKind as aa, SlimRuntimeOf as ab, SubmitHandler as ac, Unset as ad, ValidateOn as ae, ValidateOnConfig as af, ValidationError as ag, ValidationResponse as ah, ValidationResponseWithoutValue as ai, ValueOfUnion as aj, WriteMeta as ak, WriteShape as al, AcceptableDefaults as ar, SchemaFactoryOptions as as, TransformAbortHolder as at, UseFormReturnType as b, RegisterValue as c, GetDisplayState as d, ArrayItem as e, ArrayPath as f, CoercionRegistry as g, CoercionResult as h, CustomDirectiveRegisterAssignerFn as i, DeepPartial as j, DefaultValuesResponse as k, DefaultValuesShape as l, DisplayCtx as m, DisplayMachine as n, DisplayState as o, ErrorsProxyShape as p, FieldMetaPayload as q, FieldState as r, FieldStateMap as s, FieldStateMapEntry as t, FlatPath as u, FormErrorRecord as v, FormErrorsSurface as w, FormMeta as x, HistoryConfig as y, IsUnion as z };
+export { ROOT_PATH as X, ROOT_PATH_KEY as Y, canonicalizePath as al, isPathPrefix as am, isUnset as an, parseDottedPath as ao, unset as ap };
+export type { RegisterFlatPath as $, AbstractSchema as A, NestedType as B, CoercionEntry as C, DefaultValuesInput as D, ErrorInput as E, FormKey as F, GenericForm as G, HandleSubmit as H, IsTuple as I, JoinSegments as J, KeyofUnion as K, LiftedValueShape as L, MetaTrackerValue as M, NestedReadType as N, OnError as O, OnInvalidSubmitPolicy as P, OnSubmit as Q, PartialFlatPath as R, Path as S, PathKey as T, UseFormConfiguration as U, PendingValidationStatus as V, Primitive as W, ReactiveValidationStatus as Z, RegisterDirective as _, UseFormReturnType as a, RegisterOptions as a0, RegisterSelectModifier as a1, RegisterTextModifier as a2, RegisterTransform as a3, RegisterValue as a4, Segment as a5, SetValueCallback as a6, SetValuePayload as a7, SettledValidationStatus as a8, SlimPrimitiveKind as a9, SlimRuntimeOf as aa, SubmitHandler as ab, Unset as ac, ValidateOn as ad, ValidateOnConfig as ae, ValidationError as af, ValidationResponse as ag, ValidationResponseWithoutValue as ah, ValueOfUnion as ai, WriteMeta as aj, WriteShape as ak, AcceptableDefaults as aq, SchemaFactoryOptions as ar, TransformAbortHolder as as, RegisterModelDynamicCustomDirective as at, ArrayItem as b, ArrayPath as c, AttaformDefaults as d, CoercionRegistry as e, CoercionResult as f, CustomDirectiveRegisterAssignerFn as g, DeepPartial as h, DefaultValuesResponse as i, DefaultValuesShape as j, DisplayCtx as k, DisplayMachine as l, DisplayState as m, ErrorsProxyShape as n, FieldMetaPayload as o, FieldState as p, FieldStateMap as q, FieldStateMapEntry as r, FlatPath as s, FormErrorRecord as t, FormErrorsSurface as u, FormMeta as v, GetDisplayState as w, HistoryConfig as x, IsUnion as y, Json as z };

package/dist/shared/{attaform.i_LA3X9o.d.ts → attaform.C3WnCDXz.d.mts}

@@ -137,8 +137,8 @@ declare function canonicalizePath(input: string | Path): {
  * `Path` to address the form value as a whole, and the home for
  * form-level (global) errors: root `.refine()` messages, hydration
  * failures, and `setErrors` entries with no path all live at `[]`. Aggregate
- * reads (`errors()`, `meta.errors`) surface them alongside field
- * errors; `errors([])` returns the global bucket alone.
+ * reads (`errors()`, `errors([])`, `meta.errors`) surface them alongside
+ * field errors; `meta.ownErrors` returns the root bucket alone.
  *
  * The empty SEGMENT tuple `[]` is structurally unconstructible as a
  * field path, so it can never collide with a schema key, unlike the
@@ -2074,14 +2074,15 @@ type OnError = (error: ValidationError[]) => void | Promise<void>;
 type DisplayState = 'idle' | 'pending' | 'error' | 'success';
 /**
  * Keys on `FieldState` layered on FROM the display-state predicate
- * (plus `firstError`, computed alongside them). `Omit`'d from the
- * predicate's arguments so a predicate cannot read its own output and
- * form a cycle — enforced at the type level AND at runtime: the base
- * objects passed in literally lack these keys, so an `as` cast in TS
- * or a vanilla-JS caller still can't reach them. `FieldStateBase` /
- * `FormMetaBase` (field-state-api.ts) omit the same set in lockstep.
+ * (plus `firstError` / `firstOwnError`, computed alongside them).
+ * `Omit`'d from the predicate's arguments so a predicate cannot read
+ * its own output and form a cycle — enforced at the type level AND at
+ * runtime: the base objects passed in literally lack these keys, so an
+ * `as` cast in TS or a vanilla-JS caller still can't reach them.
+ * `FieldStateBase` / `FormMetaBase` (field-state-api.ts) omit the same
+ * set in lockstep.
  */
-type FieldStateDerivedKey = 'displayState' | 'showErrors' | 'showPending' | 'showSuccess' | 'showIdle' | 'firstError';
+type FieldStateDerivedKey = 'displayState' | 'showErrors' | 'showPending' | 'showSuccess' | 'showIdle' | 'firstError' | 'firstOwnError';
 /**
  * One step of the display state machine: the verdict the field should
  * render right now (`display`, projected to `displayState` and the
@@ -2163,12 +2164,13 @@ type GetDisplayState = (prev: DisplayMachine, ctx: DisplayCtx) => DisplayMachine
  * it to a `<form>`:
  *
  * ```vue
- * <form @submit.prevent="onSubmit">…</form>
+ * <form @submit="onSubmit">…</form>
  * ```
  *
- * It optionally accepts the originating `Event` so it can sit on
- * `@submit` directly (without `.prevent` if you want to call
- * `event.preventDefault()` yourself).
+ * It accepts the originating `Event` and calls `event.preventDefault()`
+ * itself, so bind it with `@submit`, not `@submit.prevent` (the
+ * modifier would only prevent the default a second time). Called
+ * imperatively with no event, the `preventDefault` step is skipped.
  */
 type SubmitHandler = (event?: Event) => Promise<void>;
 /**
@@ -3114,7 +3116,40 @@ type FieldState<Value = unknown> = {
      */
     readonly elements: readonly HTMLElement[];
     readonly updatedAt: string | null;
+    /**
+     * Every `ValidationError` in this path's SUBTREE: the node's own
+     * bucket plus every descendant's, sorted by schema-declaration order.
+     * On a leaf (no descendants) this equals `ownErrors`. On a container
+     * it rolls up the whole fieldset, so a parent's `errors` is non-empty
+     * whenever any child is invalid.
+     *
+     * For the errors pinned at THIS path alone (a container's own
+     * cross-field `.refine()`, or `setErrors` at this path), read
+     * `ownErrors`.
+     */
     readonly errors: readonly ValidationError[];
+    /**
+     * Every `ValidationError` at THIS exact path's own bucket, excluding
+     * descendants: schema errors, blank-required errors, and `setErrors`
+     * pinned here, in `schema`, `blank`, `user` order. The exact-path
+     * counterpart to the subtree-scoped `errors`.
+     *
+     * On a leaf this is the same array as `errors` (a leaf has no
+     * descendants). On a container it holds only the container's OWN
+     * errors, a cross-field `.refine()` on the fieldset or a path-less
+     * `setErrors` at this node, without dragging in any child error:
+     *
+     * ```vue
+     * <p v-if="form.fields.address.firstOwnError">
+     *   {{ form.fields.address.firstOwnError.message }}
+     * </p>
+     * ```
+     *
+     * On `form.meta` this is the root `[]` bucket: form-level errors from
+     * a root `.refine()` or a path-less `setErrors`. `form.meta.ownErrors`
+     * (with `firstOwnError`) is the banner accessor for those.
+     */
+    readonly ownErrors: readonly ValidationError[];
     /**
      * `true` while a per-field validation run is in flight at this path.
      * Reflects field-level debounced runs (`validate-on-change`) and
@@ -3235,9 +3270,28 @@ type FieldState<Value = unknown> = {
      * decides when to render it.
      *
      * On container paths, the first error in the aggregated subtree
-     * (descendants sorted by `pathOrdinal`).
+     * (descendants sorted by `pathOrdinal`). For the container's OWN
+     * first error only, read `firstOwnError`.
      */
     readonly firstError: ValidationError | undefined;
+    /**
+     * The first `ValidationError` in `ownErrors` (this exact path's own
+     * bucket), or `undefined` when that bucket is empty. Equivalent to
+     * `ownErrors[0]`, the exact-path counterpart to `firstError`.
+     *
+     * On a leaf this equals `firstError`. On a container it is the
+     * container's own cross-field error (a fieldset `.refine()`), never a
+     * child's. `form.meta.firstOwnError` is the form-level banner: the
+     * first root `[]` error from a root `.refine()` or a path-less
+     * `setErrors`:
+     *
+     * ```vue
+     * <p v-if="form.meta.firstOwnError" role="alert">
+     *   {{ form.meta.firstOwnError.message }}
+     * </p>
+     * ```
+     */
+    readonly firstOwnError: ValidationError | undefined;
     readonly path: ReadonlyArray<string | number>;
     /**
      * Stable, SSR-safe DOM id for this field, unique across every mount
@@ -3601,11 +3655,13 @@ type FormErrorsSurface<Form> = ErrorsProxyShape<Form> & {
     <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [FlatPath<Form>] ? unknown : never)): readonly ValidationError[];
     (segments: ReadonlyArray<string | number>): readonly ValidationError[];
     /**
-     * No-arg call returns the whole-form error aggregate — same as
-     * `form.meta.errors`: every field error plus the global bucket.
-     * Distinct from `form.errors([])`, which returns ONLY the global
-     * (root) bucket. Always a readonly array; empty when the form has no
-     * errors.
+     * No-arg call returns the whole-form error aggregate, the same as
+     * `form.meta.errors` and `form.errors([])`: every field error plus
+     * the root bucket. `form.errors(path)` is uniform at every depth,
+     * including `[]`, so the root is no exception. For the root bucket
+     * alone (a root `.refine()`, a path-less `setErrors`), read
+     * `form.meta.ownErrors`. Always a readonly array; empty when the form
+     * has no errors.
      */
     (): readonly ValidationError[];
 };
@@ -3732,7 +3788,7 @@ type FormMeta<F = unknown> = FieldState<F> & {
      * of each new submission attempt; stays `null` on success.
      *
      * The submit handler does NOT re-throw — its returned promise always
-     * resolves, so binding it to `@submit.prevent` never manufactures a
+     * resolves, so binding it to `@submit` never manufactures a
      * `window` unhandledrejection. This is the channel for an UNEXPECTED
      * submit failure (a thrown exception or rejected promise), read the
      * same way in templates and after an imperative `await submit()`. An
@@ -3893,10 +3949,11 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * Wraps your submit logic with validation and error routing.
      *
      * ```ts
-     * <form @submit.prevent="form.handleSubmit(
+     * const onSubmit = form.handleSubmit(
      *   (data) => api.signup(data),
      *   (errors) => console.log(errors),
-     * )">
+     * )
+     * // Bind the returned handler: <form @submit="onSubmit">
      * ```
      *
      * `data` is the strictly-typed parsed value — refinements have
@@ -4591,5 +4648,5 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
     blankPaths: ComputedRef<BlankPathsView>;
 };
 
-export { ROOT_PATH as Z, ROOT_PATH_KEY as _, canonicalizePath as am, isPathPrefix as an, isUnset as ao, parseDottedPath as ap, unset as aq };
-export type { ReactiveValidationStatus as $, AttaformDefaults as A, Json as B, CoercionEntry as C, DefaultValuesInput as D, ErrorInput as E, FormKey as F, GenericForm as G, HandleSubmit as H, IsTuple as I, JoinSegments as J, KeyofUnion as K, LiftedValueShape as L, MetaTrackerValue as M, NestedReadType as N, NestedType as O, OnError as P, OnInvalidSubmitPolicy as Q, RegisterModelDynamicCustomDirective as R, OnSubmit as S, PartialFlatPath as T, UseFormConfiguration as U, Path as V, PathKey as W, PendingValidationStatus as X, Primitive as Y, AbstractSchema as a, RegisterDirective as a0, RegisterFlatPath as a1, RegisterOptions as a2, RegisterSelectModifier as a3, RegisterTextModifier as a4, RegisterTransform as a5, Segment as a6, SetValueCallback as a7, SetValuePayload as a8, SettledValidationStatus as a9, SlimPrimitiveKind as aa, SlimRuntimeOf as ab, SubmitHandler as ac, Unset as ad, ValidateOn as ae, ValidateOnConfig as af, ValidationError as ag, ValidationResponse as ah, ValidationResponseWithoutValue as ai, ValueOfUnion as aj, WriteMeta as ak, WriteShape as al, AcceptableDefaults as ar, SchemaFactoryOptions as as, TransformAbortHolder as at, UseFormReturnType as b, RegisterValue as c, GetDisplayState as d, ArrayItem as e, ArrayPath as f, CoercionRegistry as g, CoercionResult as h, CustomDirectiveRegisterAssignerFn as i, DeepPartial as j, DefaultValuesResponse as k, DefaultValuesShape as l, DisplayCtx as m, DisplayMachine as n, DisplayState as o, ErrorsProxyShape as p, FieldMetaPayload as q, FieldState as r, FieldStateMap as s, FieldStateMapEntry as t, FlatPath as u, FormErrorRecord as v, FormErrorsSurface as w, FormMeta as x, HistoryConfig as y, IsUnion as z };
+export { ROOT_PATH as X, ROOT_PATH_KEY as Y, canonicalizePath as al, isPathPrefix as am, isUnset as an, parseDottedPath as ao, unset as ap };
+export type { RegisterFlatPath as $, AbstractSchema as A, NestedType as B, CoercionEntry as C, DefaultValuesInput as D, ErrorInput as E, FormKey as F, GenericForm as G, HandleSubmit as H, IsTuple as I, JoinSegments as J, KeyofUnion as K, LiftedValueShape as L, MetaTrackerValue as M, NestedReadType as N, OnError as O, OnInvalidSubmitPolicy as P, OnSubmit as Q, PartialFlatPath as R, Path as S, PathKey as T, UseFormConfiguration as U, PendingValidationStatus as V, Primitive as W, ReactiveValidationStatus as Z, RegisterDirective as _, UseFormReturnType as a, RegisterOptions as a0, RegisterSelectModifier as a1, RegisterTextModifier as a2, RegisterTransform as a3, RegisterValue as a4, Segment as a5, SetValueCallback as a6, SetValuePayload as a7, SettledValidationStatus as a8, SlimPrimitiveKind as a9, SlimRuntimeOf as aa, SubmitHandler as ab, Unset as ac, ValidateOn as ad, ValidateOnConfig as ae, ValidationError as af, ValidationResponse as ag, ValidationResponseWithoutValue as ah, ValueOfUnion as ai, WriteMeta as aj, WriteShape as ak, AcceptableDefaults as aq, SchemaFactoryOptions as ar, TransformAbortHolder as as, RegisterModelDynamicCustomDirective as at, ArrayItem as b, ArrayPath as c, AttaformDefaults as d, CoercionRegistry as e, CoercionResult as f, CustomDirectiveRegisterAssignerFn as g, DeepPartial as h, DefaultValuesResponse as i, DefaultValuesShape as j, DisplayCtx as k, DisplayMachine as l, DisplayState as m, ErrorsProxyShape as n, FieldMetaPayload as o, FieldState as p, FieldStateMap as q, FieldStateMapEntry as r, FlatPath as s, FormErrorRecord as t, FormErrorsSurface as u, FormMeta as v, GetDisplayState as w, HistoryConfig as x, IsUnion as y, Json as z };

package/dist/shared/{attaform.i_LA3X9o.d.mts → attaform.C3WnCDXz.d.ts}

@@ -137,8 +137,8 @@ declare function canonicalizePath(input: string | Path): {
  * `Path` to address the form value as a whole, and the home for
  * form-level (global) errors: root `.refine()` messages, hydration
  * failures, and `setErrors` entries with no path all live at `[]`. Aggregate
- * reads (`errors()`, `meta.errors`) surface them alongside field
- * errors; `errors([])` returns the global bucket alone.
+ * reads (`errors()`, `errors([])`, `meta.errors`) surface them alongside
+ * field errors; `meta.ownErrors` returns the root bucket alone.
  *
  * The empty SEGMENT tuple `[]` is structurally unconstructible as a
  * field path, so it can never collide with a schema key, unlike the
@@ -2074,14 +2074,15 @@ type OnError = (error: ValidationError[]) => void | Promise<void>;
 type DisplayState = 'idle' | 'pending' | 'error' | 'success';
 /**
  * Keys on `FieldState` layered on FROM the display-state predicate
- * (plus `firstError`, computed alongside them). `Omit`'d from the
- * predicate's arguments so a predicate cannot read its own output and
- * form a cycle — enforced at the type level AND at runtime: the base
- * objects passed in literally lack these keys, so an `as` cast in TS
- * or a vanilla-JS caller still can't reach them. `FieldStateBase` /
- * `FormMetaBase` (field-state-api.ts) omit the same set in lockstep.
+ * (plus `firstError` / `firstOwnError`, computed alongside them).
+ * `Omit`'d from the predicate's arguments so a predicate cannot read
+ * its own output and form a cycle — enforced at the type level AND at
+ * runtime: the base objects passed in literally lack these keys, so an
+ * `as` cast in TS or a vanilla-JS caller still can't reach them.
+ * `FieldStateBase` / `FormMetaBase` (field-state-api.ts) omit the same
+ * set in lockstep.
  */
-type FieldStateDerivedKey = 'displayState' | 'showErrors' | 'showPending' | 'showSuccess' | 'showIdle' | 'firstError';
+type FieldStateDerivedKey = 'displayState' | 'showErrors' | 'showPending' | 'showSuccess' | 'showIdle' | 'firstError' | 'firstOwnError';
 /**
  * One step of the display state machine: the verdict the field should
  * render right now (`display`, projected to `displayState` and the
@@ -2163,12 +2164,13 @@ type GetDisplayState = (prev: DisplayMachine, ctx: DisplayCtx) => DisplayMachine
  * it to a `<form>`:
  *
  * ```vue
- * <form @submit.prevent="onSubmit">…</form>
+ * <form @submit="onSubmit">…</form>
  * ```
  *
- * It optionally accepts the originating `Event` so it can sit on
- * `@submit` directly (without `.prevent` if you want to call
- * `event.preventDefault()` yourself).
+ * It accepts the originating `Event` and calls `event.preventDefault()`
+ * itself, so bind it with `@submit`, not `@submit.prevent` (the
+ * modifier would only prevent the default a second time). Called
+ * imperatively with no event, the `preventDefault` step is skipped.
  */
 type SubmitHandler = (event?: Event) => Promise<void>;
 /**
@@ -3114,7 +3116,40 @@ type FieldState<Value = unknown> = {
      */
     readonly elements: readonly HTMLElement[];
     readonly updatedAt: string | null;
+    /**
+     * Every `ValidationError` in this path's SUBTREE: the node's own
+     * bucket plus every descendant's, sorted by schema-declaration order.
+     * On a leaf (no descendants) this equals `ownErrors`. On a container
+     * it rolls up the whole fieldset, so a parent's `errors` is non-empty
+     * whenever any child is invalid.
+     *
+     * For the errors pinned at THIS path alone (a container's own
+     * cross-field `.refine()`, or `setErrors` at this path), read
+     * `ownErrors`.
+     */
     readonly errors: readonly ValidationError[];
+    /**
+     * Every `ValidationError` at THIS exact path's own bucket, excluding
+     * descendants: schema errors, blank-required errors, and `setErrors`
+     * pinned here, in `schema`, `blank`, `user` order. The exact-path
+     * counterpart to the subtree-scoped `errors`.
+     *
+     * On a leaf this is the same array as `errors` (a leaf has no
+     * descendants). On a container it holds only the container's OWN
+     * errors, a cross-field `.refine()` on the fieldset or a path-less
+     * `setErrors` at this node, without dragging in any child error:
+     *
+     * ```vue
+     * <p v-if="form.fields.address.firstOwnError">
+     *   {{ form.fields.address.firstOwnError.message }}
+     * </p>
+     * ```
+     *
+     * On `form.meta` this is the root `[]` bucket: form-level errors from
+     * a root `.refine()` or a path-less `setErrors`. `form.meta.ownErrors`
+     * (with `firstOwnError`) is the banner accessor for those.
+     */
+    readonly ownErrors: readonly ValidationError[];
     /**
      * `true` while a per-field validation run is in flight at this path.
      * Reflects field-level debounced runs (`validate-on-change`) and
@@ -3235,9 +3270,28 @@ type FieldState<Value = unknown> = {
      * decides when to render it.
      *
      * On container paths, the first error in the aggregated subtree
-     * (descendants sorted by `pathOrdinal`).
+     * (descendants sorted by `pathOrdinal`). For the container's OWN
+     * first error only, read `firstOwnError`.
      */
     readonly firstError: ValidationError | undefined;
+    /**
+     * The first `ValidationError` in `ownErrors` (this exact path's own
+     * bucket), or `undefined` when that bucket is empty. Equivalent to
+     * `ownErrors[0]`, the exact-path counterpart to `firstError`.
+     *
+     * On a leaf this equals `firstError`. On a container it is the
+     * container's own cross-field error (a fieldset `.refine()`), never a
+     * child's. `form.meta.firstOwnError` is the form-level banner: the
+     * first root `[]` error from a root `.refine()` or a path-less
+     * `setErrors`:
+     *
+     * ```vue
+     * <p v-if="form.meta.firstOwnError" role="alert">
+     *   {{ form.meta.firstOwnError.message }}
+     * </p>
+     * ```
+     */
+    readonly firstOwnError: ValidationError | undefined;
     readonly path: ReadonlyArray<string | number>;
     /**
      * Stable, SSR-safe DOM id for this field, unique across every mount
@@ -3601,11 +3655,13 @@ type FormErrorsSurface<Form> = ErrorsProxyShape<Form> & {
     <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [FlatPath<Form>] ? unknown : never)): readonly ValidationError[];
     (segments: ReadonlyArray<string | number>): readonly ValidationError[];
     /**
-     * No-arg call returns the whole-form error aggregate — same as
-     * `form.meta.errors`: every field error plus the global bucket.
-     * Distinct from `form.errors([])`, which returns ONLY the global
-     * (root) bucket. Always a readonly array; empty when the form has no
-     * errors.
+     * No-arg call returns the whole-form error aggregate, the same as
+     * `form.meta.errors` and `form.errors([])`: every field error plus
+     * the root bucket. `form.errors(path)` is uniform at every depth,
+     * including `[]`, so the root is no exception. For the root bucket
+     * alone (a root `.refine()`, a path-less `setErrors`), read
+     * `form.meta.ownErrors`. Always a readonly array; empty when the form
+     * has no errors.
      */
     (): readonly ValidationError[];
 };
@@ -3732,7 +3788,7 @@ type FormMeta<F = unknown> = FieldState<F> & {
      * of each new submission attempt; stays `null` on success.
      *
      * The submit handler does NOT re-throw — its returned promise always
-     * resolves, so binding it to `@submit.prevent` never manufactures a
+     * resolves, so binding it to `@submit` never manufactures a
      * `window` unhandledrejection. This is the channel for an UNEXPECTED
      * submit failure (a thrown exception or rejected promise), read the
      * same way in templates and after an imperative `await submit()`. An
@@ -3893,10 +3949,11 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * Wraps your submit logic with validation and error routing.
      *
      * ```ts
-     * <form @submit.prevent="form.handleSubmit(
+     * const onSubmit = form.handleSubmit(
      *   (data) => api.signup(data),
      *   (errors) => console.log(errors),
-     * )">
+     * )
+     * // Bind the returned handler: <form @submit="onSubmit">
      * ```
      *
      * `data` is the strictly-typed parsed value — refinements have
@@ -4591,5 +4648,5 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
     blankPaths: ComputedRef<BlankPathsView>;
 };
 
-export { ROOT_PATH as Z, ROOT_PATH_KEY as _, canonicalizePath as am, isPathPrefix as an, isUnset as ao, parseDottedPath as ap, unset as aq };
-export type { ReactiveValidationStatus as $, AttaformDefaults as A, Json as B, CoercionEntry as C, DefaultValuesInput as D, ErrorInput as E, FormKey as F, GenericForm as G, HandleSubmit as H, IsTuple as I, JoinSegments as J, KeyofUnion as K, LiftedValueShape as L, MetaTrackerValue as M, NestedReadType as N, NestedType as O, OnError as P, OnInvalidSubmitPolicy as Q, RegisterModelDynamicCustomDirective as R, OnSubmit as S, PartialFlatPath as T, UseFormConfiguration as U, Path as V, PathKey as W, PendingValidationStatus as X, Primitive as Y, AbstractSchema as a, RegisterDirective as a0, RegisterFlatPath as a1, RegisterOptions as a2, RegisterSelectModifier as a3, RegisterTextModifier as a4, RegisterTransform as a5, Segment as a6, SetValueCallback as a7, SetValuePayload as a8, SettledValidationStatus as a9, SlimPrimitiveKind as aa, SlimRuntimeOf as ab, SubmitHandler as ac, Unset as ad, ValidateOn as ae, ValidateOnConfig as af, ValidationError as ag, ValidationResponse as ah, ValidationResponseWithoutValue as ai, ValueOfUnion as aj, WriteMeta as ak, WriteShape as al, AcceptableDefaults as ar, SchemaFactoryOptions as as, TransformAbortHolder as at, UseFormReturnType as b, RegisterValue as c, GetDisplayState as d, ArrayItem as e, ArrayPath as f, CoercionRegistry as g, CoercionResult as h, CustomDirectiveRegisterAssignerFn as i, DeepPartial as j, DefaultValuesResponse as k, DefaultValuesShape as l, DisplayCtx as m, DisplayMachine as n, DisplayState as o, ErrorsProxyShape as p, FieldMetaPayload as q, FieldState as r, FieldStateMap as s, FieldStateMapEntry as t, FlatPath as u, FormErrorRecord as v, FormErrorsSurface as w, FormMeta as x, HistoryConfig as y, IsUnion as z };
+export { ROOT_PATH as X, ROOT_PATH_KEY as Y, canonicalizePath as al, isPathPrefix as am, isUnset as an, parseDottedPath as ao, unset as ap };
+export type { RegisterFlatPath as $, AbstractSchema as A, NestedType as B, CoercionEntry as C, DefaultValuesInput as D, ErrorInput as E, FormKey as F, GenericForm as G, HandleSubmit as H, IsTuple as I, JoinSegments as J, KeyofUnion as K, LiftedValueShape as L, MetaTrackerValue as M, NestedReadType as N, OnError as O, OnInvalidSubmitPolicy as P, OnSubmit as Q, PartialFlatPath as R, Path as S, PathKey as T, UseFormConfiguration as U, PendingValidationStatus as V, Primitive as W, ReactiveValidationStatus as Z, RegisterDirective as _, UseFormReturnType as a, RegisterOptions as a0, RegisterSelectModifier as a1, RegisterTextModifier as a2, RegisterTransform as a3, RegisterValue as a4, Segment as a5, SetValueCallback as a6, SetValuePayload as a7, SettledValidationStatus as a8, SlimPrimitiveKind as a9, SlimRuntimeOf as aa, SubmitHandler as ab, Unset as ac, ValidateOn as ad, ValidateOnConfig as ae, ValidationError as af, ValidationResponse as ag, ValidationResponseWithoutValue as ah, ValueOfUnion as ai, WriteMeta as aj, WriteShape as ak, AcceptableDefaults as aq, SchemaFactoryOptions as ar, TransformAbortHolder as as, RegisterModelDynamicCustomDirective as at, ArrayItem as b, ArrayPath as c, AttaformDefaults as d, CoercionRegistry as e, CoercionResult as f, CustomDirectiveRegisterAssignerFn as g, DeepPartial as h, DefaultValuesResponse as i, DefaultValuesShape as j, DisplayCtx as k, DisplayMachine as l, DisplayState as m, ErrorsProxyShape as n, FieldMetaPayload as o, FieldState as p, FieldStateMap as q, FieldStateMapEntry as r, FlatPath as s, FormErrorRecord as t, FormErrorsSurface as u, FormMeta as v, GetDisplayState as w, HistoryConfig as x, IsUnion as y, Json as z };

package/dist/shared/{attaform.DuzQYscR.d.ts → attaform.C9fPTxjB.d.cts}

@@ -1,10 +1,10 @@
 interface WebpackFamilyPluginOptions {
     /**
-     * Rewrite `attaform/zod` imports at build time to the matching adapter
-     * subpath, based on the consumer's installed Zod major. Default `true`.
-     * Set to `false` to keep the runtime-dispatch unified entry (ships both
-     * adapters) when a project intentionally mixes Zod versions or resolves
-     * Zod in a non-standard way.
+     * Rewrite `attaform` and `attaform/zod` imports at build time to the
+     * matching adapter subpath, based on the consumer's installed Zod major.
+     * Default `true`. Set to `false` to keep the runtime-dispatch unified
+     * entry (ships both adapters) when a project intentionally mixes Zod
+     * versions or resolves Zod in a non-standard way.
      */
     resolveZodAlias?: boolean;
     /**

package/dist/shared/{attaform.DuzQYscR.d.cts → attaform.C9fPTxjB.d.mts}

@@ -1,10 +1,10 @@
 interface WebpackFamilyPluginOptions {
     /**
-     * Rewrite `attaform/zod` imports at build time to the matching adapter
-     * subpath, based on the consumer's installed Zod major. Default `true`.
-     * Set to `false` to keep the runtime-dispatch unified entry (ships both
-     * adapters) when a project intentionally mixes Zod versions or resolves
-     * Zod in a non-standard way.
+     * Rewrite `attaform` and `attaform/zod` imports at build time to the
+     * matching adapter subpath, based on the consumer's installed Zod major.
+     * Default `true`. Set to `false` to keep the runtime-dispatch unified
+     * entry (ships both adapters) when a project intentionally mixes Zod
+     * versions or resolves Zod in a non-standard way.
      */
     resolveZodAlias?: boolean;
     /**

package/dist/shared/{attaform.DuzQYscR.d.mts → attaform.C9fPTxjB.d.ts}

@@ -1,10 +1,10 @@
 interface WebpackFamilyPluginOptions {
     /**
-     * Rewrite `attaform/zod` imports at build time to the matching adapter
-     * subpath, based on the consumer's installed Zod major. Default `true`.
-     * Set to `false` to keep the runtime-dispatch unified entry (ships both
-     * adapters) when a project intentionally mixes Zod versions or resolves
-     * Zod in a non-standard way.
+     * Rewrite `attaform` and `attaform/zod` imports at build time to the
+     * matching adapter subpath, based on the consumer's installed Zod major.
+     * Default `true`. Set to `false` to keep the runtime-dispatch unified
+     * entry (ships both adapters) when a project intentionally mixes Zod
+     * versions or resolves Zod in a non-standard way.
      */
     resolveZodAlias?: boolean;
     /**