attaform 0.16.2 → 0.16.4

package/dist/shared/{attaform.0Gxd_OOx.d.cts → attaform.CU3JperC.d.cts}

@@ -2,14 +2,22 @@ import { Ref, ObjectDirective, ComputedRef } from 'vue';
 
 /**
  * Schema-attached field metadata — the shared types used by both Zod
- * adapters (`attaform/zod` for v4 and `attaform/zod-v3` for v3) so a
- * consumer's data flow reads the same shape regardless of adapter.
- *
- * The Zod 4 adapter creates a typed `z.registry<FieldMetaPayload>()`
- * and writes through `schema.register(fieldMeta, payload)` (native) or
- * the `withMeta(schema, payload)` helper. The Zod 3 adapter has no
- * native registry — it shims a `WeakMap<ZodTypeAny, FieldMetaPayload>`
- * with the same write API via `withMeta`.
+ * adapters and the unified `attaform/zod` entry so a consumer's data
+ * flow reads the same shape regardless of which path runs at lookup.
+ *
+ * Storage lives in the cross-adapter `field-meta-store` core: a pair
+ * of WeakMaps (single-payload for last-write-wins reads, list-of-
+ * payloads for shared-schema disambiguation). Every entry's
+ * `fieldMeta` re-exports the same registry-shaped object, so
+ * `withMeta`/`fieldMeta.add` writes from one entry surface at lookup
+ * through any other.
+ *
+ * `withMeta(schema, payload)` clones the schema before registering,
+ * so each call gets fresh identity (the WeakMap keys on reference).
+ * The cloning strategy depends on the major: Zod 4 schemas use the
+ * native `.clone()`, Zod 3 schemas reconstruct via constructor +
+ * `_def`. The unified entry's `withMeta` runtime-branches on which
+ * one is in play.
  *
  * Reads are unified through `AbstractSchema.getFieldMetaAtPath(path)`,
  * which returns a fully-resolved `ResolvedFieldMeta` (label /
@@ -90,10 +98,15 @@ type Path = readonly Segment[];
  * ```ts
  * parseDottedPath('user.address.line1')   // ['user', 'address', 'line1']
  * parseDottedPath('items.0.name')         // ['items', 0, 'name']
- * parseDottedPath('')                     // [] (root)
+ * parseDottedPath('')                     // ['']  (the empty-string key)
  * ```
  *
- * Throws `InvalidPathError` for paths with empty segments
+ * The empty-string input `''` is the **literal empty-key path**, not
+ * the root. Use the array form `[]` for root. Form-level errors
+ * (root `.refine()`) live at the empty-string path bucket so
+ * `errors('')` returns them without sweeping every field error too.
+ *
+ * Throws `InvalidPathError` for paths with empty INTERNAL segments
  * (`'a..b'`, leading or trailing dots). For keys containing literal
  * dots, pass an array form (`['user.name']`) instead.
  */
@@ -457,9 +470,10 @@ type FormKey = string;
 /**
  * One validation failure. `path` points at the offending field as a
  * structured array — `['user', 'address', 0, 'line1']` for a nested
- * field, `[]` for a form-level error. `formKey` identifies which
- * form produced the error so a single error list can be routed to
- * multiple forms.
+ * field, `['']` (the empty-string path) for a form-level error
+ * (root `.refine()` messages, `setFormErrors()` entries, server-
+ * emitted form banners). `formKey` identifies which form produced
+ * the error so a single error list can be routed to multiple forms.
  *
  * Returned by `validate()` / `validateAsync()` / `handleSubmit`'s
  * `onError` callback, and by `parseApiErrors` for server responses.
@@ -467,7 +481,12 @@ type FormKey = string;
 type ValidationError = {
     /** Human-readable message describing the failure. */
     message: string;
-    /** Structured path of the offending field. Empty array means a form-level error. */
+    /**
+     * Structured path of the offending field. The empty-string path
+     * `['']` is the form-level bucket — the dedicated home for errors
+     * that don't belong to any specific field, distinct from the
+     * whole-form subtree address `[]`.
+     */
     path: (string | number)[];
     /** Identifies which form produced this error. */
     formKey: FormKey;
@@ -844,8 +863,8 @@ type AbstractSchema<Form, GetValueFormType> = {
      * Return the resolved field metadata for the schema node at `path`
      * — label, description, placeholder, plus the full registered
      * payload as `meta` for consumer-augmented keys. Reads through the
-     * adapter's metadata mechanism (Zod 4: `z.registry()`; Zod 3:
-     * a WeakMap shim) and applies these one-way fallbacks:
+     * shared cross-adapter field-meta store and applies these one-way
+     * fallbacks:
      *
      *   - `label`:       registry payload → `humanize(lastSegment)`
      *   - `description`: registry payload → `schema.description`
@@ -1386,6 +1405,17 @@ type UseFormConfiguration<Form extends GenericForm, GetValueFormType, Schema ext
      * coerced.
      */
     coerce?: boolean | CoercionRegistry;
+    /**
+     * Per-form override of the `shouldShowErrors` heuristic that drives
+     * `field.showErrors` and `form.meta.showErrors`. Falls back to
+     * `AttaformDefaults.shouldShowErrors`, then to the library default
+     * (`defaultShouldShowErrors`). See `AttaformDefaults.shouldShowErrors`
+     * for the resolution rules and predicate signature.
+     *
+     * Boolean shorthand: `true` → always show *when errors exist*;
+     * `false` → never show.
+     */
+    shouldShowErrors?: ShouldShowErrorsConfig;
 };
 /**
  * App-level defaults applied to every `useForm` call. Set these once
@@ -1451,6 +1481,34 @@ type AttaformDefaults = {
      * authoritative writes whose strict typing is on the caller.
      */
     coerce?: boolean | CoercionRegistry;
+    /**
+     * Default for `useForm({ shouldShowErrors })`. Centralised heuristic
+     * that drives `field.showErrors` (and `form.meta.showErrors`) — a
+     * boolean that gates whether a path's errors are *ready* to render.
+     *
+     * Resolution order (per-form wins):
+     *
+     *   useForm({ shouldShowErrors })  >  AttaformDefaults  >  library default
+     *
+     * The library default reads "show after the first submit attempt OR
+     * after the field has been interacted with AND changed":
+     *
+     * ```ts
+     * (field, formMeta) =>
+     *   formMeta.submitCount > 0 || (field.touched === true && field.dirty)
+     * ```
+     *
+     * Compose with the library default via the public
+     * `defaultShouldShowErrors` export. Boolean shorthand is supported:
+     * `true` → always show *when errors exist*; `false` → never show. The
+     * predicate is invoked only when `errors.length > 0`, so authors
+     * don't re-check inside.
+     *
+     * The predicate's args are `Omit`'d of `showErrors` / `firstError`
+     * to prevent recursive predicates — those are derived FROM this
+     * predicate, so reading them inside would be a self-reference.
+     */
+    shouldShowErrors?: ShouldShowErrorsConfig;
 };
 /**
  * Callback invoked by `handleSubmit` after the form parses successfully.
@@ -1465,6 +1523,46 @@ type OnSubmit<Form extends GenericForm> = (form: Form) => void | Promise<void>;
  * automatic `onInvalidSubmit` UI nudge).
  */
 type OnError = (error: ValidationError[]) => void | Promise<void>;
+/**
+ * Predicate that drives `field.showErrors` (and `form.meta.showErrors`).
+ * Receives the field's reactive state plus the form's reactive meta;
+ * returns `true` to render the field's errors, `false` to keep them
+ * hidden. The framework gates the call on `errors.length > 0`, so
+ * authors don't re-check error presence inside.
+ *
+ * Both arguments are `Omit`'d of `showErrors` / `firstError` — those
+ * are derived FROM this predicate, so reading them inside would be a
+ * self-reference. The omit is enforced at the type level AND at
+ * runtime: the keys literally are not present on the objects passed
+ * in, so `as` casting in TS or vanilla-JS bypass cannot create a
+ * cycle.
+ *
+ * The library default — `defaultShouldShowErrors` — is publicly
+ * exported so a layered predicate can compose with it:
+ *
+ * ```ts
+ * import { defaultShouldShowErrors } from 'attaform'
+ *
+ * useForm({
+ *   schema,
+ *   shouldShowErrors: (field, formMeta) =>
+ *     field.path[0] === 'urgent' || defaultShouldShowErrors(field, formMeta),
+ * })
+ * ```
+ */
+type ShouldShowErrors = (field: Omit<FieldState, 'showErrors' | 'firstError'>, formMeta: Omit<FormMeta, 'showErrors' | 'firstError'>) => boolean;
+/**
+ * Configuration shape for `shouldShowErrors`. A predicate function or
+ * a boolean shorthand:
+ *
+ * - `true` — always show errors (when any exist).
+ * - `false` — never show errors.
+ * - function — custom predicate, see `ShouldShowErrors`.
+ *
+ * Resolved through three tiers (per-form > plugin defaults > library
+ * default).
+ */
+type ShouldShowErrorsConfig = ShouldShowErrors | boolean;
 /**
  * Submit handler returned by `handleSubmit(onSubmit, onError)`. Bind
  * it to a `<form>`:
@@ -2067,13 +2165,58 @@ type FieldState<Value = unknown> = {
      * green-checkmark / `aria-invalid` UX.
      */
     readonly valid: boolean;
+    /**
+     * Centralised "should I render this field's errors right now?"
+     * gate. Wraps `errors.length > 0 && shouldShowErrors(field, formMeta)`
+     * so templates avoid re-spelling the heuristic at every error site:
+     *
+     * ```vue
+     * <span v-if="form.fields.email.showErrors">
+     *   {{ form.fields.email.firstError?.message }}
+     * </span>
+     * ```
+     *
+     * The heuristic itself comes from `useForm({ shouldShowErrors })` →
+     * `createAttaform({ defaults: { shouldShowErrors } })` → library
+     * default (`defaultShouldShowErrors` — show after first submit OR
+     * after touched-and-dirty). Override per form, app-wide, or
+     * compose with `defaultShouldShowErrors` for a layered predicate.
+     *
+     * Falls back to `false` whenever there are no errors — the gate
+     * skips the predicate entirely in that case.
+     *
+     * Available on container paths too: `form.fields.users[0].showErrors`
+     * aggregates over the row's descendants (any descendant with a
+     * qualifying error flips the container on).
+     */
+    readonly showErrors: boolean;
+    /**
+     * The first `ValidationError` at this path in the deterministic
+     * schema-declaration order — equivalent to `errors[0]`, exposed as
+     * a sugar accessor for the common case of "show the highest-priority
+     * error message and ignore the rest":
+     *
+     * ```vue
+     * <span v-if="form.fields.email.showErrors">
+     *   {{ form.fields.email.firstError?.message }}
+     * </span>
+     * ```
+     *
+     * `undefined` when no errors exist. Independent of `showErrors` —
+     * the data primitive is always available; the heuristic only
+     * decides when to render it.
+     *
+     * On container paths, the first error in the aggregated subtree
+     * (descendants sorted by `pathOrdinal`).
+     */
+    readonly firstError: ValidationError | undefined;
     readonly path: ReadonlyArray<string | number>;
     readonly blank: boolean;
     /**
      * Presentational label for this field. Resolves through the
-     * adapter's metadata mechanism — Zod 4's `z.registry()` (typed
-     * payload via `schema.register(fieldMeta, {...})` or the
-     * `withMeta()` helper); Zod 3's WeakMap shim — and falls back to
+     * shared cross-adapter field-meta store — written via
+     * `schema.register(fieldMeta, {...})` (Zod 4 native chain) or the
+     * `withMeta()` helper (works on both majors) — and falls back to
      * a humanized form of the path's last segment when nothing has
      * been registered. Always a string.
      *
@@ -2782,12 +2925,15 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * if (result.ok) form.setFormErrors(result.errors)
      * ```
      *
-     * Form-level errors surface in `form.meta.errors` (alongside field
-     * errors) but are intentionally excluded from the path-keyed
-     * `form.errors` proxy (no key represents `[]` in a nested object) —
-     * read them via `meta.errors.filter(e => e.path.length === 0)` or
-     * `form.errors([])` (the call-form aggregates everywhere, including
-     * form-level errors at `path: []`).
+     * Form-level errors land at the empty-string path bucket
+     * (`path: ['']`). They surface in `form.meta.errors` (alongside
+     * field errors), in `form.errors()` / `form.errors([])` (whole-form
+     * subtree aggregates), and — uniquely — in `form.errors('')`,
+     * which returns ONLY the form-level bucket. They're excluded from
+     * the path-keyed `form.errors` drill proxy because no nested-object
+     * key represents the empty-string path. Read them via
+     * `meta.errors.filter(e => e.path.length === 1 && e.path[0] === '')`
+     * if you need a programmatic split.
      */
     setFormErrors: (errors: ReadonlyArray<Partial<ValidationError> & {
         message: string;
@@ -2897,6 +3043,26 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * `options` is forwarded to `Element.scrollIntoView` unchanged.
      */
     scrollToFirstError: (options?: ScrollIntoViewOptions) => boolean;
+    /**
+     * Programmatically mark fields as touched — the sticky flag the
+     * standard "show errors after interaction" pattern reads. Closes
+     * the gap when fields are populated without a DOM gesture (post-
+     * import, paste, autofill, server-seeded values you want to
+     * validate immediately).
+     *
+     * ```ts
+     * form.touch('email')                 // one leaf
+     * form.touch('profile')               // every leaf under profile
+     * form.touch(['profile', 'name'])     // segment-array form
+     * form.touch()                        // every leaf in the form
+     * ```
+     *
+     * Pure flag write — does not mutate value, focused, blurred, or
+     * trigger validation. Idempotent: re-calling on an already-touched
+     * field is a no-op. Touched is sticky-true; pair with
+     * `form.reset()` / `form.resetField()` to clear.
+     */
+    touch: (path?: FlatPath<Form> | (string | number)[]) => void;
     /**
      * Append `value` to the array at `path`.
      *
@@ -2948,5 +3114,5 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
     blankPaths: ComputedRef<ReadonlySet<string>>;
 };
 
-export { ROOT_PATH as Z, ROOT_PATH_KEY as _, canonicalizePath as ak, isPathPrefix as al, isUnset as am, parseDottedPath as an, unset as ao };
-export type { ReactiveValidationStatus as $, AttaformDefaults as A, OnInvalidSubmitPolicy as B, CoercionRegistry as C, DeepPartial as D, OnSubmit 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, Path as P, PathKey as Q, RegisterValue as R, SlimPrimitiveKind as S, PendingValidationStatus as T, UseFormConfiguration as U, ValidationError as V, PersistConfig as W, PersistConfigOptions as X, PersistIncludeMode as Y, CoercionEntry 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, SlimRuntimeOf as aa, SubmitHandler as ab, Unset as ac, ValidateOn as ad, ValidateOnConfig as ae, ValidationResponse as af, ValidationResponseWithoutValue as ag, ValueOfUnion as ah, WriteMeta as ai, WriteShape as aj, AbstractSchema as b, DefaultValuesShape as c, UseFormReturnType as d, RegisterModelDynamicCustomDirective as e, ApiErrorEnvelope as f, ApiErrorDetails as g, ApiErrorEntry as h, ArrayItem as i, ArrayPath as j, CoercionResult as k, CustomDirectiveRegisterAssignerFn as l, DefaultValuesResponse as m, FieldMetaPayload as n, FieldState as o, FieldStateMap as p, FieldStateMapEntry as q, FlatPath as r, FormErrorRecord as s, FormErrorsSurface as t, FormMeta as u, FormStorage as v, FormStorageKind as w, HistoryConfig as x, IsUnion as y, NestedType as z };
+export { ROOT_PATH_KEY as $, ROOT_PATH as _, canonicalizePath as am, isPathPrefix as an, isUnset as ao, parseDottedPath as ap, unset as aq };
+export type { AttaformDefaults as A, NestedType as B, CoercionRegistry as C, DeepPartial as D, OnInvalidSubmitPolicy 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, OnSubmit as P, Path as Q, RegisterValue as R, SlimPrimitiveKind as S, PathKey as T, UseFormConfiguration as U, ValidationError as V, PendingValidationStatus as W, PersistConfig as X, PersistConfigOptions as Y, PersistIncludeMode as Z, CoercionEntry as a, ReactiveValidationStatus as a0, RegisterDirective as a1, RegisterFlatPath as a2, RegisterOptions as a3, RegisterSelectModifier as a4, RegisterTextModifier as a5, RegisterTransform as a6, Segment as a7, SetValueCallback as a8, SetValuePayload as a9, SettledValidationStatus as aa, ShouldShowErrorsConfig as ab, SlimRuntimeOf as ac, SubmitHandler as ad, Unset as ae, ValidateOn as af, ValidateOnConfig as ag, ValidationResponse as ah, ValidationResponseWithoutValue as ai, ValueOfUnion as aj, WriteMeta as ak, WriteShape as al, AbstractSchema as b, DefaultValuesShape as c, UseFormReturnType as d, RegisterModelDynamicCustomDirective as e, ShouldShowErrors as f, ApiErrorEnvelope as g, ApiErrorDetails as h, ApiErrorEntry as i, ArrayItem as j, ArrayPath as k, CoercionResult as l, CustomDirectiveRegisterAssignerFn as m, DefaultValuesResponse 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, FormStorage as w, FormStorageKind as x, HistoryConfig as y, IsUnion as z };

package/dist/shared/{attaform.0Gxd_OOx.d.mts → attaform.CU3JperC.d.mts}

@@ -2,14 +2,22 @@ import { Ref, ObjectDirective, ComputedRef } from 'vue';
 
 /**
  * Schema-attached field metadata — the shared types used by both Zod
- * adapters (`attaform/zod` for v4 and `attaform/zod-v3` for v3) so a
- * consumer's data flow reads the same shape regardless of adapter.
- *
- * The Zod 4 adapter creates a typed `z.registry<FieldMetaPayload>()`
- * and writes through `schema.register(fieldMeta, payload)` (native) or
- * the `withMeta(schema, payload)` helper. The Zod 3 adapter has no
- * native registry — it shims a `WeakMap<ZodTypeAny, FieldMetaPayload>`
- * with the same write API via `withMeta`.
+ * adapters and the unified `attaform/zod` entry so a consumer's data
+ * flow reads the same shape regardless of which path runs at lookup.
+ *
+ * Storage lives in the cross-adapter `field-meta-store` core: a pair
+ * of WeakMaps (single-payload for last-write-wins reads, list-of-
+ * payloads for shared-schema disambiguation). Every entry's
+ * `fieldMeta` re-exports the same registry-shaped object, so
+ * `withMeta`/`fieldMeta.add` writes from one entry surface at lookup
+ * through any other.
+ *
+ * `withMeta(schema, payload)` clones the schema before registering,
+ * so each call gets fresh identity (the WeakMap keys on reference).
+ * The cloning strategy depends on the major: Zod 4 schemas use the
+ * native `.clone()`, Zod 3 schemas reconstruct via constructor +
+ * `_def`. The unified entry's `withMeta` runtime-branches on which
+ * one is in play.
  *
  * Reads are unified through `AbstractSchema.getFieldMetaAtPath(path)`,
  * which returns a fully-resolved `ResolvedFieldMeta` (label /
@@ -90,10 +98,15 @@ type Path = readonly Segment[];
  * ```ts
  * parseDottedPath('user.address.line1')   // ['user', 'address', 'line1']
  * parseDottedPath('items.0.name')         // ['items', 0, 'name']
- * parseDottedPath('')                     // [] (root)
+ * parseDottedPath('')                     // ['']  (the empty-string key)
  * ```
  *
- * Throws `InvalidPathError` for paths with empty segments
+ * The empty-string input `''` is the **literal empty-key path**, not
+ * the root. Use the array form `[]` for root. Form-level errors
+ * (root `.refine()`) live at the empty-string path bucket so
+ * `errors('')` returns them without sweeping every field error too.
+ *
+ * Throws `InvalidPathError` for paths with empty INTERNAL segments
  * (`'a..b'`, leading or trailing dots). For keys containing literal
  * dots, pass an array form (`['user.name']`) instead.
  */
@@ -457,9 +470,10 @@ type FormKey = string;
 /**
  * One validation failure. `path` points at the offending field as a
  * structured array — `['user', 'address', 0, 'line1']` for a nested
- * field, `[]` for a form-level error. `formKey` identifies which
- * form produced the error so a single error list can be routed to
- * multiple forms.
+ * field, `['']` (the empty-string path) for a form-level error
+ * (root `.refine()` messages, `setFormErrors()` entries, server-
+ * emitted form banners). `formKey` identifies which form produced
+ * the error so a single error list can be routed to multiple forms.
  *
  * Returned by `validate()` / `validateAsync()` / `handleSubmit`'s
  * `onError` callback, and by `parseApiErrors` for server responses.
@@ -467,7 +481,12 @@ type FormKey = string;
 type ValidationError = {
     /** Human-readable message describing the failure. */
     message: string;
-    /** Structured path of the offending field. Empty array means a form-level error. */
+    /**
+     * Structured path of the offending field. The empty-string path
+     * `['']` is the form-level bucket — the dedicated home for errors
+     * that don't belong to any specific field, distinct from the
+     * whole-form subtree address `[]`.
+     */
     path: (string | number)[];
     /** Identifies which form produced this error. */
     formKey: FormKey;
@@ -844,8 +863,8 @@ type AbstractSchema<Form, GetValueFormType> = {
      * Return the resolved field metadata for the schema node at `path`
      * — label, description, placeholder, plus the full registered
      * payload as `meta` for consumer-augmented keys. Reads through the
-     * adapter's metadata mechanism (Zod 4: `z.registry()`; Zod 3:
-     * a WeakMap shim) and applies these one-way fallbacks:
+     * shared cross-adapter field-meta store and applies these one-way
+     * fallbacks:
      *
      *   - `label`:       registry payload → `humanize(lastSegment)`
      *   - `description`: registry payload → `schema.description`
@@ -1386,6 +1405,17 @@ type UseFormConfiguration<Form extends GenericForm, GetValueFormType, Schema ext
      * coerced.
      */
     coerce?: boolean | CoercionRegistry;
+    /**
+     * Per-form override of the `shouldShowErrors` heuristic that drives
+     * `field.showErrors` and `form.meta.showErrors`. Falls back to
+     * `AttaformDefaults.shouldShowErrors`, then to the library default
+     * (`defaultShouldShowErrors`). See `AttaformDefaults.shouldShowErrors`
+     * for the resolution rules and predicate signature.
+     *
+     * Boolean shorthand: `true` → always show *when errors exist*;
+     * `false` → never show.
+     */
+    shouldShowErrors?: ShouldShowErrorsConfig;
 };
 /**
  * App-level defaults applied to every `useForm` call. Set these once
@@ -1451,6 +1481,34 @@ type AttaformDefaults = {
      * authoritative writes whose strict typing is on the caller.
      */
     coerce?: boolean | CoercionRegistry;
+    /**
+     * Default for `useForm({ shouldShowErrors })`. Centralised heuristic
+     * that drives `field.showErrors` (and `form.meta.showErrors`) — a
+     * boolean that gates whether a path's errors are *ready* to render.
+     *
+     * Resolution order (per-form wins):
+     *
+     *   useForm({ shouldShowErrors })  >  AttaformDefaults  >  library default
+     *
+     * The library default reads "show after the first submit attempt OR
+     * after the field has been interacted with AND changed":
+     *
+     * ```ts
+     * (field, formMeta) =>
+     *   formMeta.submitCount > 0 || (field.touched === true && field.dirty)
+     * ```
+     *
+     * Compose with the library default via the public
+     * `defaultShouldShowErrors` export. Boolean shorthand is supported:
+     * `true` → always show *when errors exist*; `false` → never show. The
+     * predicate is invoked only when `errors.length > 0`, so authors
+     * don't re-check inside.
+     *
+     * The predicate's args are `Omit`'d of `showErrors` / `firstError`
+     * to prevent recursive predicates — those are derived FROM this
+     * predicate, so reading them inside would be a self-reference.
+     */
+    shouldShowErrors?: ShouldShowErrorsConfig;
 };
 /**
  * Callback invoked by `handleSubmit` after the form parses successfully.
@@ -1465,6 +1523,46 @@ type OnSubmit<Form extends GenericForm> = (form: Form) => void | Promise<void>;
  * automatic `onInvalidSubmit` UI nudge).
  */
 type OnError = (error: ValidationError[]) => void | Promise<void>;
+/**
+ * Predicate that drives `field.showErrors` (and `form.meta.showErrors`).
+ * Receives the field's reactive state plus the form's reactive meta;
+ * returns `true` to render the field's errors, `false` to keep them
+ * hidden. The framework gates the call on `errors.length > 0`, so
+ * authors don't re-check error presence inside.
+ *
+ * Both arguments are `Omit`'d of `showErrors` / `firstError` — those
+ * are derived FROM this predicate, so reading them inside would be a
+ * self-reference. The omit is enforced at the type level AND at
+ * runtime: the keys literally are not present on the objects passed
+ * in, so `as` casting in TS or vanilla-JS bypass cannot create a
+ * cycle.
+ *
+ * The library default — `defaultShouldShowErrors` — is publicly
+ * exported so a layered predicate can compose with it:
+ *
+ * ```ts
+ * import { defaultShouldShowErrors } from 'attaform'
+ *
+ * useForm({
+ *   schema,
+ *   shouldShowErrors: (field, formMeta) =>
+ *     field.path[0] === 'urgent' || defaultShouldShowErrors(field, formMeta),
+ * })
+ * ```
+ */
+type ShouldShowErrors = (field: Omit<FieldState, 'showErrors' | 'firstError'>, formMeta: Omit<FormMeta, 'showErrors' | 'firstError'>) => boolean;
+/**
+ * Configuration shape for `shouldShowErrors`. A predicate function or
+ * a boolean shorthand:
+ *
+ * - `true` — always show errors (when any exist).
+ * - `false` — never show errors.
+ * - function — custom predicate, see `ShouldShowErrors`.
+ *
+ * Resolved through three tiers (per-form > plugin defaults > library
+ * default).
+ */
+type ShouldShowErrorsConfig = ShouldShowErrors | boolean;
 /**
  * Submit handler returned by `handleSubmit(onSubmit, onError)`. Bind
  * it to a `<form>`:
@@ -2067,13 +2165,58 @@ type FieldState<Value = unknown> = {
      * green-checkmark / `aria-invalid` UX.
      */
     readonly valid: boolean;
+    /**
+     * Centralised "should I render this field's errors right now?"
+     * gate. Wraps `errors.length > 0 && shouldShowErrors(field, formMeta)`
+     * so templates avoid re-spelling the heuristic at every error site:
+     *
+     * ```vue
+     * <span v-if="form.fields.email.showErrors">
+     *   {{ form.fields.email.firstError?.message }}
+     * </span>
+     * ```
+     *
+     * The heuristic itself comes from `useForm({ shouldShowErrors })` →
+     * `createAttaform({ defaults: { shouldShowErrors } })` → library
+     * default (`defaultShouldShowErrors` — show after first submit OR
+     * after touched-and-dirty). Override per form, app-wide, or
+     * compose with `defaultShouldShowErrors` for a layered predicate.
+     *
+     * Falls back to `false` whenever there are no errors — the gate
+     * skips the predicate entirely in that case.
+     *
+     * Available on container paths too: `form.fields.users[0].showErrors`
+     * aggregates over the row's descendants (any descendant with a
+     * qualifying error flips the container on).
+     */
+    readonly showErrors: boolean;
+    /**
+     * The first `ValidationError` at this path in the deterministic
+     * schema-declaration order — equivalent to `errors[0]`, exposed as
+     * a sugar accessor for the common case of "show the highest-priority
+     * error message and ignore the rest":
+     *
+     * ```vue
+     * <span v-if="form.fields.email.showErrors">
+     *   {{ form.fields.email.firstError?.message }}
+     * </span>
+     * ```
+     *
+     * `undefined` when no errors exist. Independent of `showErrors` —
+     * the data primitive is always available; the heuristic only
+     * decides when to render it.
+     *
+     * On container paths, the first error in the aggregated subtree
+     * (descendants sorted by `pathOrdinal`).
+     */
+    readonly firstError: ValidationError | undefined;
     readonly path: ReadonlyArray<string | number>;
     readonly blank: boolean;
     /**
      * Presentational label for this field. Resolves through the
-     * adapter's metadata mechanism — Zod 4's `z.registry()` (typed
-     * payload via `schema.register(fieldMeta, {...})` or the
-     * `withMeta()` helper); Zod 3's WeakMap shim — and falls back to
+     * shared cross-adapter field-meta store — written via
+     * `schema.register(fieldMeta, {...})` (Zod 4 native chain) or the
+     * `withMeta()` helper (works on both majors) — and falls back to
      * a humanized form of the path's last segment when nothing has
      * been registered. Always a string.
      *
@@ -2782,12 +2925,15 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * if (result.ok) form.setFormErrors(result.errors)
      * ```
      *
-     * Form-level errors surface in `form.meta.errors` (alongside field
-     * errors) but are intentionally excluded from the path-keyed
-     * `form.errors` proxy (no key represents `[]` in a nested object) —
-     * read them via `meta.errors.filter(e => e.path.length === 0)` or
-     * `form.errors([])` (the call-form aggregates everywhere, including
-     * form-level errors at `path: []`).
+     * Form-level errors land at the empty-string path bucket
+     * (`path: ['']`). They surface in `form.meta.errors` (alongside
+     * field errors), in `form.errors()` / `form.errors([])` (whole-form
+     * subtree aggregates), and — uniquely — in `form.errors('')`,
+     * which returns ONLY the form-level bucket. They're excluded from
+     * the path-keyed `form.errors` drill proxy because no nested-object
+     * key represents the empty-string path. Read them via
+     * `meta.errors.filter(e => e.path.length === 1 && e.path[0] === '')`
+     * if you need a programmatic split.
      */
     setFormErrors: (errors: ReadonlyArray<Partial<ValidationError> & {
         message: string;
@@ -2897,6 +3043,26 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * `options` is forwarded to `Element.scrollIntoView` unchanged.
      */
     scrollToFirstError: (options?: ScrollIntoViewOptions) => boolean;
+    /**
+     * Programmatically mark fields as touched — the sticky flag the
+     * standard "show errors after interaction" pattern reads. Closes
+     * the gap when fields are populated without a DOM gesture (post-
+     * import, paste, autofill, server-seeded values you want to
+     * validate immediately).
+     *
+     * ```ts
+     * form.touch('email')                 // one leaf
+     * form.touch('profile')               // every leaf under profile
+     * form.touch(['profile', 'name'])     // segment-array form
+     * form.touch()                        // every leaf in the form
+     * ```
+     *
+     * Pure flag write — does not mutate value, focused, blurred, or
+     * trigger validation. Idempotent: re-calling on an already-touched
+     * field is a no-op. Touched is sticky-true; pair with
+     * `form.reset()` / `form.resetField()` to clear.
+     */
+    touch: (path?: FlatPath<Form> | (string | number)[]) => void;
     /**
      * Append `value` to the array at `path`.
      *
@@ -2948,5 +3114,5 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
     blankPaths: ComputedRef<ReadonlySet<string>>;
 };
 
-export { ROOT_PATH as Z, ROOT_PATH_KEY as _, canonicalizePath as ak, isPathPrefix as al, isUnset as am, parseDottedPath as an, unset as ao };
-export type { ReactiveValidationStatus as $, AttaformDefaults as A, OnInvalidSubmitPolicy as B, CoercionRegistry as C, DeepPartial as D, OnSubmit 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, Path as P, PathKey as Q, RegisterValue as R, SlimPrimitiveKind as S, PendingValidationStatus as T, UseFormConfiguration as U, ValidationError as V, PersistConfig as W, PersistConfigOptions as X, PersistIncludeMode as Y, CoercionEntry 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, SlimRuntimeOf as aa, SubmitHandler as ab, Unset as ac, ValidateOn as ad, ValidateOnConfig as ae, ValidationResponse as af, ValidationResponseWithoutValue as ag, ValueOfUnion as ah, WriteMeta as ai, WriteShape as aj, AbstractSchema as b, DefaultValuesShape as c, UseFormReturnType as d, RegisterModelDynamicCustomDirective as e, ApiErrorEnvelope as f, ApiErrorDetails as g, ApiErrorEntry as h, ArrayItem as i, ArrayPath as j, CoercionResult as k, CustomDirectiveRegisterAssignerFn as l, DefaultValuesResponse as m, FieldMetaPayload as n, FieldState as o, FieldStateMap as p, FieldStateMapEntry as q, FlatPath as r, FormErrorRecord as s, FormErrorsSurface as t, FormMeta as u, FormStorage as v, FormStorageKind as w, HistoryConfig as x, IsUnion as y, NestedType as z };
+export { ROOT_PATH_KEY as $, ROOT_PATH as _, canonicalizePath as am, isPathPrefix as an, isUnset as ao, parseDottedPath as ap, unset as aq };
+export type { AttaformDefaults as A, NestedType as B, CoercionRegistry as C, DeepPartial as D, OnInvalidSubmitPolicy 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, OnSubmit as P, Path as Q, RegisterValue as R, SlimPrimitiveKind as S, PathKey as T, UseFormConfiguration as U, ValidationError as V, PendingValidationStatus as W, PersistConfig as X, PersistConfigOptions as Y, PersistIncludeMode as Z, CoercionEntry as a, ReactiveValidationStatus as a0, RegisterDirective as a1, RegisterFlatPath as a2, RegisterOptions as a3, RegisterSelectModifier as a4, RegisterTextModifier as a5, RegisterTransform as a6, Segment as a7, SetValueCallback as a8, SetValuePayload as a9, SettledValidationStatus as aa, ShouldShowErrorsConfig as ab, SlimRuntimeOf as ac, SubmitHandler as ad, Unset as ae, ValidateOn as af, ValidateOnConfig as ag, ValidationResponse as ah, ValidationResponseWithoutValue as ai, ValueOfUnion as aj, WriteMeta as ak, WriteShape as al, AbstractSchema as b, DefaultValuesShape as c, UseFormReturnType as d, RegisterModelDynamicCustomDirective as e, ShouldShowErrors as f, ApiErrorEnvelope as g, ApiErrorDetails as h, ApiErrorEntry as i, ArrayItem as j, ArrayPath as k, CoercionResult as l, CustomDirectiveRegisterAssignerFn as m, DefaultValuesResponse 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, FormStorage as w, FormStorageKind as x, HistoryConfig as y, IsUnion as z };