attaform 0.18.1 → 0.19.0

package/dist/shared/{attaform.Dj9mwbaV.d.mts → attaform.C0uGZQ4M.d.cts}

@@ -319,6 +319,26 @@ type ArrayPath<Form, P extends FlatPath<Form> = FlatPath<Form>> = P extends stri
  * constrain `Path extends ArrayPath<Form>` so this is always well-defined.
  */
 type ArrayItem<Form, Path extends ArrayPath<Form>> = NestedType<Form, Path> extends ReadonlyArray<infer Item> ? Item : never;
+/**
+ * Companion to `ArrayPath`: filter `FlatPath<Form>` down to the subset
+ * of paths whose resolved leaf is a record (an object with an open
+ * string-keyed index signature, e.g. `z.record(z.string(), V)`). A
+ * fixed-shape object (`z.object({ ... })`) is excluded — its keys are
+ * statically known, so it has no `string` index signature.
+ *
+ * `string extends keyof T` is the index-signature probe: it holds for
+ * `Record<string, V>` (`keyof` is `string`) and fails for a fixed object
+ * (`keyof` is the literal key union). The leading array guard keeps
+ * arrays (which also satisfy the object check) out of the record set.
+ */
+type RecordPath<Form, P extends FlatPath<Form> = FlatPath<Form>> = P extends string ? NestedType<Form, P> extends readonly unknown[] ? never : NestedType<Form, P> extends Record<string, unknown> ? string extends keyof NestedType<Form, P> ? P : never : never : never;
+/**
+ * Value type of the record addressed by `Path` — the `V` in a
+ * `Record<string, V>`. Callers constrain `Path extends RecordPath<Form>`,
+ * so the leaf is always an open string-keyed record and this is
+ * well-defined.
+ */
+type RecordValue<Form, Path extends RecordPath<Form>> = NestedType<Form, Path> extends Record<string, infer Value> ? Value : never;
 /**
  * Widens primitive-literal leaves to their primitive supertype to
  * match the runtime "slim-primitive write contract."
@@ -1308,20 +1328,24 @@ type WriteMeta = {
      */
     readonly skipDiscriminatorReshape?: boolean;
     /**
-     * Hint about an array structural mutation, set by `field-arrays.ts`
-     * helpers so `setValueAtPath` can surgically clear variant memory
-     * for indices the operation invalidated. Without this hint, a raw
-     * whole-array `setValue(arrayPath, [...])` clears all memory under
-     * the array (the runtime can't tell which indices stayed put).
-     * Internal — don't set from consumer code.
+     * Records an array structural mutation precisely enough to replay the
+     * exact index permutation it produced, set by `field-arrays.ts`
+     * helpers. `setValueAtPath` uses it to surgically clear variant memory
+     * for the indices the operation invalidated. Without this hint, a raw
+     * whole-array `setValue(arrayPath, [...])` clears all memory under the
+     * array (the runtime can't tell which indices stayed put). Internal —
+     * don't set from consumer code.
      */
     readonly arrayOp?: {
-        readonly kind: 'shift-from';
+        readonly kind: 'insert';
+        readonly index: number;
+    } | {
+        readonly kind: 'remove';
         readonly index: number;
     } | {
-        readonly kind: 'shift-range';
-        readonly fromIndex: number;
-        readonly toIndex: number;
+        readonly kind: 'move';
+        readonly from: number;
+        readonly to: number;
     } | {
         readonly kind: 'swap';
         readonly a: number;
@@ -1736,16 +1760,14 @@ type UseFormConfiguration<Form extends GenericForm, GetValueFormType, Schema ext
      */
     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.
+     * Per-form override of the `getDisplayState` heuristic that drives
+     * `field.displayState` and the `show*` booleans (and their `form.meta`
+     * rollups). Falls back to `AttaformDefaults.getDisplayState`, then to
+     * the library default (`defaultDisplayState`). See
+     * `AttaformDefaults.getDisplayState` for the resolution rules and
+     * predicate signature.
      */
-    shouldShowErrors?: ShouldShowErrorsConfig;
+    getDisplayState?: GetDisplayState;
     /**
      * Recursion ceiling for schema walks that descend through recursive
      * schemas (Zod's `z.lazy(...)` today). Default `64`. Per-form value
@@ -1818,6 +1840,20 @@ type UseFormConfiguration<Form extends GenericForm, GetValueFormType, Schema ext
      * channel would be solo by construction.
      */
     multiTab?: boolean;
+    /**
+     * Whether `v-register` automatically manages aria attributes
+     * (`aria-invalid`, `aria-busy`, `aria-required`, `aria-describedby`)
+     * from the field's display state. **Defaults to `true`.**
+     *
+     * **Resolution order (per-register override > per-form > global > library):**
+     *
+     *   register(path, { autoAria })  >  useForm({ autoAria })  >  AttaformDefaults.autoAria  >  library default (`true`)
+     *
+     * Set `false` to leave all aria wiring to your own markup form-wide.
+     * Any aria attribute you author yourself is always left untouched,
+     * independent of this flag.
+     */
+    autoAria?: boolean;
     /**
      * @internal
      * SSR prefetch mark — set by the `attaform/vite` compile-time
@@ -1899,33 +1935,41 @@ type AttaformDefaults = {
      */
     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.
+     * Default for `useForm({ getDisplayState })`. The centralised
+     * heuristic that resolves every path's `field.displayState` — and thus
+     * the `show*` booleans and their `form.meta` rollups — to one of
+     * `'idle' | 'pending' | 'error' | 'success'`.
      *
      * Resolution order (per-form wins):
      *
-     *   useForm({ shouldShowErrors })  >  AttaformDefaults  >  library default
+     *   useForm({ getDisplayState })  >  AttaformDefaults  >  library default
      *
-     * The library default reads "show after the first submit attempt OR
-     * after the field has been interacted with AND changed":
+     * The library default opens one timing gate, then resolves by
+     * precedence: gate closed → `'idle'`; a run in flight → `'pending'`;
+     * an own-path error → `'error'`; otherwise `valid` → `'success'`, else
+     * `'idle'`. The gate opens after the first submit attempt OR once the
+     * field is touched and not currently focused:
      *
      * ```ts
-     * (field, formMeta) =>
-     *   formMeta.submissionAttempts > 0 || (field.touched === true && field.dirty)
+     * (field, formMeta) => {
+     *   const gateOpen =
+     *     formMeta.submissionAttempts > 0 ||
+     *     (field.touched === true && field.focused !== true)
+     *   if (!gateOpen) return 'idle'
+     *   if (field.validating === true) return 'pending'
+     *   // ...own-path error → 'error'; valid → 'success'; else 'idle'
+     * }
      * ```
      *
-     * 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.
+     * Compose with the library default via the public `defaultDisplayState`
+     * export. The predicate runs on every field-state read, so it owns the
+     * idle / pending / error / success decision outright.
      *
-     * 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.
+     * The predicate's args are `Omit`'d of the derived `displayState` /
+     * `show*` / `firstError` keys (see `FieldStateDerivedKey`) to prevent
+     * a self-referential predicate.
      */
-    shouldShowErrors?: ShouldShowErrorsConfig;
+    getDisplayState?: GetDisplayState;
     /**
      * Default for `useForm({ maxRecursionDepth })`. Recursion ceiling
      * for schema walks that descend through recursive schemas (Zod's
@@ -2025,6 +2069,21 @@ type AttaformDefaults = {
      * the multi-tab-sync recipe's Security section for the threat model.
      */
     multiTab?: boolean;
+    /**
+     * App-wide default for `useForm({ autoAria })`. Library default is
+     * `true`: `v-register` keeps `aria-invalid` / `aria-busy` /
+     * `aria-required` / `aria-describedby` in sync with each field's
+     * display state out of the box.
+     *
+     * **Resolution order (per-form wins):**
+     *
+     *   useForm({ autoAria })  >  AttaformDefaults.autoAria  >  library default (`true`)
+     *
+     * Set `false` once at the plugin level to make every form manage its
+     * own aria markup. Authored aria attributes are always preserved
+     * regardless of this setting.
+     */
+    autoAria?: boolean;
 };
 /**
  * Callback invoked by `handleSubmit` after the form parses successfully.
@@ -2040,45 +2099,59 @@ type OnSubmit<Form extends GenericForm> = (form: Form) => void | Promise<void>;
  */
 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:
+ * The display-state verdict at a path: the single signal a UI needs to
+ * decide what (if anything) to surface about validation right now.
+ * Rolled up at containers and at the form root (`form.meta.displayState`).
+ *
+ * - `'idle'` — nothing to surface. Either pre-interaction (the timing
+ *   gate hasn't opened) or gate-open with no verdict worth showing.
+ * - `'pending'` — a validation run is in flight at this path; the prior
+ *   verdict is stale. Drive a spinner / "Checking…" affordance.
+ * - `'error'` — a blocking error the timing gate has cleared for display.
+ * - `'success'` — validation passed and the gate has cleared a positive
+ *   confirmation (the green-check pattern).
+ *
+ * The four `show*` booleans on `FieldState` are sugar over this enum
+ * (`showErrors === (displayState === 'error')`, and so on), so they can
+ * never contradict it.
+ */
+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.
+ */
+type FieldStateDerivedKey = 'displayState' | 'showErrors' | 'showPending' | 'showSuccess' | 'showIdle' | 'firstError';
+/**
+ * Predicate that resolves a path's `displayState`. Receives the field's
+ * reactive state plus the form's reactive meta (both minus the derived
+ * `displayState` / `show*` / `firstError` keys — see `FieldStateDerivedKey`)
+ * and returns the single enum verdict; the `show*` booleans derive from
+ * the result. Runs unconditionally on every field-state read, so the
+ * idle / pending / error / success decision lives in exactly one place
+ * and the whole app's validation-display behavior flows from it.
+ *
+ * The library default — `defaultDisplayState` — is publicly exported so
+ * a layered predicate can compose with it:
  *
  * ```ts
- * import { defaultShouldShowErrors } from 'attaform'
+ * import { defaultDisplayState } from 'attaform'
  *
  * useForm({
  *   schema,
- *   shouldShowErrors: (field, formMeta) =>
- *     field.path[0] === 'urgent' || defaultShouldShowErrors(field, formMeta),
+ *   // Defer to the default everywhere, but never show a success check on `username`.
+ *   getDisplayState: (field, formMeta) => {
+ *     const state = defaultDisplayState(field, formMeta)
+ *     return field.path[0] === 'username' && state === 'success' ? 'idle' : state
+ *   },
  * })
  * ```
  */
-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;
+type GetDisplayState = (field: Omit<FieldState, FieldStateDerivedKey>, formMeta: Omit<FormMeta, FieldStateDerivedKey>) => DisplayState;
 /**
  * Submit handler returned by `handleSubmit(onSubmit, onError)`. Bind
  * it to a `<form>`:
@@ -2330,6 +2403,22 @@ type RegisterOptions = {
      * instead — see the "Custom assigners" section in the API docs.
      */
     transforms?: ReadonlyArray<RegisterTransform>;
+    /**
+     * Per-binding override for automatic aria management, the narrowest
+     * tier of the `autoAria` cascade. By default the directive keeps
+     * `aria-invalid` / `aria-busy` / `aria-required` / `aria-describedby`
+     * in sync with the field's display state. Pass `autoAria: false` to
+     * leave every aria attribute on this element to you (the directive
+     * still manages value binding and registration), or `autoAria: true`
+     * to re-enable management on one binding even when the form set
+     * `useForm({ autoAria: false })`.
+     *
+     * Overrides `useForm({ autoAria })` and
+     * `createAttaform({ defaults: { autoAria } })`. Writing an aria
+     * attribute yourself also locks the directive out of that one
+     * attribute, regardless of this flag.
+     */
+    autoAria?: boolean;
 };
 /**
  * The object returned by `form.register(path)`. Pass it to a native
@@ -2530,6 +2619,16 @@ type RegisterValue<Value = unknown> = Readonly<{
      * @internal
      */
     markBlank: () => boolean;
+    /**
+     * Flip this field's sticky `interacted` flag — the signal that the
+     * user has issued at least one value edit here (an insert or a
+     * delete). Called by the directive's input / change listeners on
+     * every genuine user input; never by hydration or programmatic
+     * writes. Idempotent (the store skips the write once set). Don't
+     * call from consumer code.
+     * @internal
+     */
+    markInteracted: () => void;
     /**
      * `true` when the schema's slim primitive set at this path includes
      * `'undefined'` — i.e. the leaf was declared `.optional()` (or as
@@ -2561,6 +2660,42 @@ type RegisterValue<Value = unknown> = Readonly<{
      * @internal
      */
     acceptsString: boolean;
+    /**
+     * The field's aria satellite ids, mirroring `FieldState.aria`. The
+     * directive points `aria-describedby` at `errorId` while the field
+     * is in its error state. Optional so hand-rolled `RegisterValue`
+     * mocks don't have to declare it; the directive skips aria wiring
+     * when absent.
+     * @internal
+     */
+    aria?: {
+        readonly errorId: string;
+        readonly descriptionId: string;
+    };
+    /**
+     * Whether the schema marks this path required, from
+     * `schema.isRequiredAtPath(segments)`. Drives `aria-required`.
+     * Optional for the same mock-tolerance reason as `aria`.
+     * @internal
+     */
+    isRequired?: boolean;
+    /**
+     * Whether the directive should auto-manage aria attributes for this
+     * binding. Resolves the per-register `autoAria` override against the
+     * form-level value: `options.autoAria ?? formAutoAria`. The directive
+     * treats an absent value as off.
+     * @internal
+     */
+    ariaEnabled?: boolean;
+    /**
+     * The gated display-state verdict for this path, reusing the same
+     * field-state identity as `form.fields`. The directive watches it to
+     * keep `aria-invalid` / `aria-busy` / `aria-describedby` in lockstep
+     * with the visible error state, even on async ticks with no parent
+     * re-render. Optional; the directive skips aria wiring when absent.
+     * @internal
+     */
+    ariaDisplayState?: Readonly<Ref<DisplayState>>;
 }>;
 /**
  * Custom assigner installed on an element via the directive's
@@ -2876,6 +3011,32 @@ type FieldState<Value = unknown> = {
     readonly focused: boolean | null;
     readonly blurred: boolean | null;
     readonly touched: boolean;
+    /**
+     * `true` once the user has issued at least one value edit on this
+     * field through `v-register` (an insert or a delete), sticky
+     * thereafter and preserved across disconnects. Distinct from
+     * `dirty`: typing `"a"` then deleting it back to empty leaves the
+     * field net-unchanged (`dirty: false`) yet `interacted: true`.
+     * Distinct from `touched`: tabbing through a field without editing
+     * flips `touched` but never `interacted`. Set only by user input,
+     * never by hydration or programmatic `setValue`; cleared by
+     * `form.reset()` / `form.resetField(path)`. Containers roll it up as
+     * a disjunction (any descendant interacted).
+     */
+    readonly interacted: boolean;
+    /**
+     * `true` once the user has blurred this field after editing it: the
+     * first time they edit a value and then leave. Sticky thereafter and
+     * preserved across disconnects; a tab-through with no edit never sets
+     * it (`interacted` is still false at that blur). It composes
+     * `interacted` with the departure and drives the default display gate,
+     * so errors reveal once the user finishes a pass and leaves, then stay
+     * visible through a re-focus to be fixed live. Set only by user
+     * input/blur, never by hydration or programmatic writes; cleared by
+     * `form.reset()` / `form.resetField(path)`. Containers roll it up as a
+     * disjunction.
+     */
+    readonly blurredAfterInteraction: boolean;
     readonly connected: boolean;
     /**
      * The first DOM element bound to this path via `v-register`, or
@@ -2932,9 +3093,29 @@ type FieldState<Value = unknown> = {
      */
     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:
+     * The single display-state verdict at this path: `'idle'`,
+     * `'pending'`, `'error'`, or `'success'`. The source of truth the
+     * four `show*` booleans below derive from. Bind it directly when one
+     * branch over the set reads cleaner than four flags:
+     *
+     * ```vue
+     * <FieldStatusIcon :state="form.fields.email.displayState" />
+     * ```
+     *
+     * Resolved by the `getDisplayState` heuristic:
+     * `useForm({ getDisplayState })` →
+     * `createAttaform({ defaults: { getDisplayState } })` → library
+     * default (`defaultDisplayState`). Override per form, app-wide, or
+     * compose with `defaultDisplayState` for a layered predicate.
+     *
+     * Available on container paths too: `form.fields.users[0].displayState`
+     * rolls up over the row's descendants.
+     */
+    readonly displayState: DisplayState;
+    /**
+     * `displayState === 'error'`. The centralised "render this field's
+     * errors right now?" gate, so templates avoid re-spelling the
+     * heuristic at every error site:
      *
      * ```vue
      * <span v-if="form.fields.email.showErrors">
@@ -2942,20 +3123,29 @@ type FieldState<Value = unknown> = {
      * </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).
+     * Kept plural to match `errors` / `firstError`. On container paths it
+     * rolls up over descendants (any descendant resolving to `'error'`
+     * flips the container on).
      */
     readonly showErrors: boolean;
+    /**
+     * `displayState === 'pending'`. A per-field validation run is in
+     * flight at this path and the prior verdict is stale; drive a spinner
+     * or a "Checking…" affordance.
+     */
+    readonly showPending: boolean;
+    /**
+     * `displayState === 'success'`. Validation has passed and the timing
+     * gate has cleared a positive confirmation; drive the green-check
+     * pattern.
+     */
+    readonly showSuccess: boolean;
+    /**
+     * `displayState === 'idle'`. Nothing to surface yet — pre-interaction,
+     * or gate-open with no verdict worth showing. Read it to suppress
+     * helper text the moment any other signal takes over.
+     */
+    readonly showIdle: boolean;
     /**
      * The first `ValidationError` at this path in the deterministic
      * schema-declaration order — equivalent to `errors[0]`, exposed as
@@ -2977,6 +3167,53 @@ type FieldState<Value = unknown> = {
      */
     readonly firstError: ValidationError | undefined;
     readonly path: ReadonlyArray<string | number>;
+    /**
+     * Stable, SSR-safe DOM id for this field, unique across every mount
+     * on the page. Derived from the form's key and this path, folded with
+     * the form's per-mount `instanceId` so two simultaneous mounts of the
+     * same keyed form never collide. Bind it to wire a label and its
+     * input without inventing your own id:
+     *
+     * ```vue
+     * <label :for="form.fields.email.id">Email</label>
+     * <input :id="form.fields.email.id" v-register="form.register('email')" />
+     * ```
+     *
+     * Treat as identity, not state: stable for the path across the form's
+     * lifetime, opaque, not meant to be parsed.
+     */
+    readonly id: string;
+    /**
+     * Satellite ids derived from {@link id} for the elements that
+     * describe this field. Wire them to an error node and a description
+     * node so assistive tech announces them with the input. The
+     * `v-register` directive points `aria-describedby` at `errorId`
+     * automatically while the field is in its error state; you render the
+     * matching element and id it:
+     *
+     * ```vue
+     * <input v-register="form.register('email')" />
+     * <span :id="form.fields.email.aria.errorId" v-if="form.fields.email.showErrors">
+     *   {{ form.fields.email.firstError?.message }}
+     * </span>
+     * ```
+     *
+     * `descriptionId` is for opt-in help text; chain it into your own
+     * `aria-describedby` when you render a persistent description element.
+     */
+    readonly aria: {
+        readonly errorId: string;
+        readonly descriptionId: string;
+    };
+    /**
+     * Stable identity for this field as an element of its parent array,
+     * suitable as a Vue `:key` when iterating array elements. An allocated
+     * token (not derived from the element's value) that follows the
+     * element across inserts, removals, moves, and swaps, so a row keeps
+     * its component instance across a reorder. Empty for fields that are
+     * not array elements. Treat as opaque identity, not state.
+     */
+    readonly key: string;
     readonly blank: boolean;
     /**
      * Presentational label for this field. Resolves through the
@@ -3422,8 +3659,8 @@ type FormMeta<F = unknown> = FieldState<F> & {
      *
      * Pure introspection counter — useful for "this form has been
      * visited and left" UX (analytics, prior-step badges, layered
-     * `shouldShowErrors` predicates) but does NOT drive the library's
-     * default `shouldShowErrors` heuristic. The reveal-on-submit story
+     * `getDisplayState` predicates) but does NOT drive the library's
+     * default `getDisplayState` heuristic. The reveal-on-submit story
      * runs entirely through `submissionAttempts`, which
      * `wizard.handleSubmit` bumps on the active form at intermediate
      * steps and on every form at the final step.
@@ -4217,6 +4454,48 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
     move: <Path extends ArrayPath<Form>>(path: Path, from: number, to: number) => void;
     /** Replace the element at `index` with `value`. No-op when out of range. */
     replace: <Path extends ArrayPath<Form>>(path: Path, index: number, value: ArrayItem<Form, Path>) => void;
+    /**
+     * Read-only, reactive view of the array at `path` as one `FieldState`
+     * per element, in index order. Each entry carries its element `key`,
+     * an allocated identity token, so a `v-for` keyed by it keeps a row's
+     * component instance across an insert, removal, move, or swap:
+     *
+     * ```vue
+     * <div v-for="(row, i) in form.list('contacts')" :key="row.key">
+     *   <input v-register="form.register(`contacts.${i}.name`)" />
+     *   <p v-if="row.showErrors">{{ row.firstError?.message }}</p>
+     * </div>
+     * ```
+     *
+     * Entries are the same field states `form.fields` exposes, so reads
+     * stay live. `form.fields(path)` remains the single aggregated
+     * container for the whole array; `list` is the per-element view.
+     * For a record, reach for `record`, which keys each entry by its own
+     * key.
+     */
+    list: <Path extends ArrayPath<Form>>(path: Path) => readonly FieldState<ArrayItem<Form, Path>>[];
+    /**
+     * Read-only, reactive view of the record at `path` as one `FieldState`
+     * per entry, keyed by the entry's own key. Where `list` hands back an
+     * ordered array for an array path, `record` hands back a keyed object
+     * for a record path, so you iterate it by key:
+     *
+     * ```vue
+     * <div v-for="(field, key) in form.record('scoresByTeam')" :key="key">
+     *   <label>{{ key }}</label>
+     *   <input v-register="form.register(`scoresByTeam.${key}`)" />
+     *   <p v-if="field.showErrors">{{ field.firstError?.message }}</p>
+     * </div>
+     * ```
+     *
+     * Entries are the same field states `form.fields` exposes, so reads
+     * stay live, and the keyed shape mirrors the record's own keys: an
+     * entry appears once you write its key (`form.setValue`) and drops
+     * when the key leaves. `form.fields(path)` remains the single
+     * aggregated container for the whole record; `record` is the
+     * per-entry view.
+     */
+    record: <Path extends RecordPath<Form>>(path: Path) => Readonly<Record<string, FieldState<RecordValue<Form, Path>>>>;
     /**
      * Read-only view of the form's blank path set. Reactive — Vue 3.5
      * tracks `.has()` / `for..of` / size accesses, so consumers can drive
@@ -4244,5 +4523,5 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
     blankPaths: ComputedRef<BlankPathsView>;
 };
 
-export { ROOT_PATH as a2, ROOT_PATH_KEY as a3, canonicalizePath as aq, isPathPrefix as ar, isUnset as as, parseDottedPath as at, unset as au };
-export type { PersistConfigOptions as $, AttaformDefaults as A, IsUnion as B, CoercionEntry as C, DefaultValuesInput as D, ErrorsProxyShape 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, RegisterValue as R, Segment as S, OnSubmit as T, UseFormConfiguration as U, ValidationError as V, PartialFlatPath as W, Path as X, PathKey as Y, PendingValidationStatus as Z, PersistConfig as _, AbstractSchema as a, PersistIncludeMode as a0, Primitive as a1, ReactiveValidationStatus as a4, RegisterDirective as a5, RegisterFlatPath as a6, RegisterOptions as a7, RegisterSelectModifier as a8, RegisterTextModifier as a9, RegisterTransform as aa, SetValueCallback as ab, SetValuePayload as ac, SettledValidationStatus as ad, ShouldShowErrorsConfig as ae, SlimPrimitiveKind as af, SlimRuntimeOf as ag, SubmitHandler as ah, Unset as ai, ValidateOn as aj, ValidateOnConfig as ak, ValidationResponse as al, ValidationResponseWithoutValue as am, ValueOfUnion as an, WriteMeta as ao, WriteShape as ap, SchemaFactoryOptions as av, PersistOptInRegistry as aw, UseFormReturnType as b, RegisterModelDynamicCustomDirective as c, ShouldShowErrors 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, FieldMetaPayload as p, FieldState as q, FieldStateMap as r, FieldStateMapEntry as s, FlatPath as t, FormErrorRecord as u, FormErrorsSurface as v, FormMeta as w, FormStorage as x, FormStorageKind as y, HistoryConfig as z };
+export { ROOT_PATH_KEY as $, ROOT_PATH as _, canonicalizePath as as, isPathPrefix as at, isUnset as au, parseDottedPath as av, unset as aw };
+export type { AbstractSchema as A, NestedType as B, CoercionEntry as C, DeepPartial as D, ErrorsProxyShape as E, FieldMetaPayload 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, PendingValidationStatus as U, PersistConfig as V, PersistConfigOptions as W, PersistIncludeMode as X, PersistOptInRegistry as Y, Primitive as Z, ApiErrorDetails as a, ReactiveValidationStatus as a0, RegisterDirective as a1, RegisterFlatPath as a2, RegisterModelDynamicCustomDirective as a3, RegisterOptions as a4, RegisterSelectModifier as a5, RegisterTextModifier as a6, RegisterTransform as a7, RegisterValue as a8, SchemaFactoryOptions as a9, Segment as aa, SetValueCallback as ab, SetValuePayload as ac, SettledValidationStatus as ad, SlimPrimitiveKind as ae, SlimRuntimeOf as af, SubmitHandler as ag, Unset as ah, UseFormConfiguration as ai, UseFormReturnType as aj, ValidateOn as ak, ValidateOnConfig as al, ValidationError as am, ValidationResponse as an, ValidationResponseWithoutValue as ao, ValueOfUnion as ap, WriteMeta as aq, WriteShape as ar, ApiErrorEntry as b, ApiErrorEnvelope as c, ArrayItem as d, ArrayPath as e, AttaformDefaults as f, CoercionRegistry as g, CoercionResult as h, CustomDirectiveRegisterAssignerFn as i, DefaultValuesInput as j, DefaultValuesResponse as k, DefaultValuesShape as l, DisplayState as m, FieldState as n, FieldStateMap as o, FieldStateMapEntry as p, FlatPath as q, FormErrorRecord as r, FormErrorsSurface as s, FormKey as t, FormMeta as u, FormStorage as v, FormStorageKind as w, GetDisplayState as x, HistoryConfig as y, IsUnion as z };