attaform 0.18.2 → 0.20.0

package/dist/shared/{attaform.CGX1CNpz.d.ts → attaform.Bh3ACtts.d.ts}

@@ -1,4 +1,4 @@
-import { s as FormKey, ae as SlimPrimitiveKind, C as CoercionEntry, g as CoercionRegistry, G as GenericForm, R as PathKey, Q as Path, am as ValidationError, A as AbstractSchema, ac as ShouldShowErrors, aq as WriteMeta, D as DeepPartial, ar as WriteShape, ak as ValidateOn, W as PersistOptInRegistry, a8 as Segment, f as AttaformDefaults, aj as UseFormReturnType, a6 as RegisterValue } from './attaform.Ca5_6Ky-.js';
+import { t as FormKey, ae as SlimPrimitiveKind, C as CoercionEntry, g as CoercionRegistry, G as GenericForm, T as PathKey, S as Path, am as ValidationError, A as AbstractSchema, x as GetDisplayState, aq as WriteMeta, D as DeepPartial, ar as WriteShape, ak as ValidateOn, Y as PersistOptInRegistry, f as AttaformDefaults, aj as UseFormReturnType, a8 as RegisterValue } from './attaform.SfhU0OEY.js';
 import { Ref, ComputedRef, App, InjectionKey } from 'vue';
 
 /**
@@ -61,7 +61,7 @@ type FormStatus = {
  * entry carries the formKey + path tuple so consumers can route to the
  * offending field from a wizard-wide error summary.
  */
-type AggregateError = {
+type WizardAggregateError = {
     readonly formKey: FormKey;
     readonly path: ReadonlyArray<string | number>;
     readonly message: string;
@@ -213,7 +213,7 @@ type WizardOnSubmit = (ctx: WizardSubmitContext) => void | Promise<void>;
  * validation and activation failures (`atta:activation-failed`). Sync
  * or async; the returned promise gates `wizard.submitting`.
  */
-type WizardOnError = (errors: readonly AggregateError[]) => void | Promise<void>;
+type WizardOnError = (errors: readonly WizardAggregateError[]) => void | Promise<void>;
 /**
  * Options for `useWizard({ steps, … })`. `steps` is the only required
  * field; the rest are optional and default sensibly for the common
@@ -439,7 +439,7 @@ type UseWizardReturnType<S extends ReadonlyArray<StepSlot> = ReadonlyArray<StepS
     readonly count: number;
     readonly statuses: WizardStatusesProxy<Record<string, FormStatus>>;
     readonly allValues: Readonly<Record<FormKey, unknown>>;
-    readonly allErrors: Readonly<Record<FormKey, readonly AggregateError[]>>;
+    readonly allErrors: Readonly<Record<FormKey, readonly WizardAggregateError[]>>;
     readonly progress: number;
     readonly canAdvance: boolean;
     readonly canGoBack: boolean;
@@ -517,19 +517,29 @@ declare const defaultCoercionRules: CoercionRegistry;
  */
 /**
  * Per-path field status. Replaced wholesale (not mutated in place) on
- * every change. Three semantic groups:
+ * every change. Five semantic groups:
  *
  *   - `connected` — is a DOM element registered for this path?
  *   - `focused` / `blurred` — DOM-state flags. `null` while no element
  *     is connected (no DOM means the concepts don't apply); plain
  *     booleans once connected, with the invariant `blurred === !focused`
  *     enforced by `markFocused`.
- *   - `touched` — interaction history, not DOM state. Always a plain
+ *   - `touched` — focus/blur history, not DOM state. Always a plain
  *     boolean: `false` at registration, sticky `true` after first blur,
  *     cleared only by `form.reset()` / `form.resetField(path)`. Persists
  *     across disconnects so v-if'd-away fields don't lose their touched
  *     state on rehide (wizard "show review of touched fields" patterns
  *     rely on this).
+ *   - `interacted` — value-mutation history, not DOM state. Plain
+ *     boolean: `false` at registration, sticky `true` once the user
+ *     issues a value edit through the directive's input listeners
+ *     (never on hydration, default seeding, or programmatic setValue);
+ *     cleared with `touched` by `form.reset()` / `form.resetField(path)`.
+ *   - `blurredAfterInteraction` — the first blur that follows a value
+ *     edit (the field has been edited and then left). Plain boolean,
+ *     sticky `true`. A tab-through blur with no prior edit does NOT set
+ *     it (`interacted` is still false at that blur). Composes
+ *     `interacted` with the departure; drives the default display gate.
  */
 type FieldRecord = {
     readonly path: Path;
@@ -538,6 +548,8 @@ type FieldRecord = {
     readonly focused: boolean | null;
     readonly blurred: boolean | null;
     readonly touched: boolean;
+    readonly interacted: boolean;
+    readonly blurredAfterInteraction: boolean;
 };
 /** Per-path DOM element tracking. Client-only. */
 type ElementRecord = {
@@ -649,15 +661,14 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
      */
     readonly ssr: boolean;
     /**
-     * Resolved `shouldShowErrors` predicate driving `field.showErrors`
-     * and `form.meta.showErrors`. Resolved once at construction via
-     * `resolveShouldShowErrors(options.shouldShowErrors)` so the
-     * field-state computeds don't repeat the boolean-vs-function
-     * branch on every read. Boolean shorthand has already been lifted
-     * to a constant predicate by the time it lands here; `undefined`
-     * config falls through to `defaultShouldShowErrors`.
+     * Resolved `getDisplayState` predicate driving `field.displayState`,
+     * the `show*` booleans, and their `form.meta` rollups. Resolved once
+     * at construction via `resolveGetDisplayState(options.getDisplayState)`;
+     * `undefined` config falls through to `defaultDisplayState`. The
+     * field-state computeds read the resolved function directly on every
+     * read.
      */
-    readonly shouldShowErrors: ShouldShowErrors;
+    readonly getDisplayState: GetDisplayState;
     readonly submitting: Ref<boolean>;
     readonly activeSubmissions: Ref<number>;
     readonly submissionAttempts: Ref<number>;
@@ -690,6 +701,15 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
      * plain-value forms. Read by `form.rehydrate()`.
      */
     readonly defaultValuesFactory: Ref<(() => unknown | Promise<unknown>) | undefined>;
+    /**
+     * `true` when this store carries an SSR prefetch queue (server path
+     * where `state.activate()` must enqueue intent before deciding
+     * whether to fire). The flag lets `buildFormApi` skip the lazy
+     * activation gate for forms with no factory AND no SSR prefetch —
+     * the common client-side case where `gated()` is otherwise pure
+     * reactive overhead on every public method call.
+     */
+    readonly hasSsrPrefetch: boolean;
     /**
      * `true` once the form's effective defaults have been applied —
      * sync `defaultValues` at construction, or async factory whose
@@ -786,6 +806,14 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
      * answer.
      */
     pathHasAsyncValidation(path: Path): boolean;
+    /**
+     * Precomputed-key shortcut for `pathHasAsyncValidation`. The
+     * canonical key is required and must correspond to `segments`; the
+     * helper skips the `canonicalizePath` round-trip so descendant-walk
+     * loops (whose Map iteration already yields the canonical key) can
+     * read the async-gate verdict without a per-leaf canonicalize.
+     */
+    pathHasAsyncValidationByKey(key: PathKey, segments: Path): boolean;
     /**
      * Per-path counter of in-flight field-level validation runs.
      * `field.validating` on `FieldState` mirrors
@@ -831,16 +859,16 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
      */
     setValueAtPath(path: Path, value: unknown, meta?: WriteMeta): boolean;
     getValueAtPath(path: Path): unknown;
-    reset(nextDefaultValues?: DeepPartial<WriteShape<F>>): void;
-    resetField(path: Path): void;
     /**
-     * Wipe `path` (or the whole form when `path === ''`) to the
-     * schema's "appropriate nullish value" — the underlying type's
-     * empty/falsy concrete, with `.default()` / `.catch()` wrappers
-     * INTENTIONALLY skipped. Sugar for
-     * `setValueAtPath(path, schema.getEmptyValueAtPath(path))`.
+     * Stable identity for the array element at `path`. An array element
+     * (numeric last segment) carries its allocated identity token,
+     * maintained by `array-identity.ts` across structural mutations.
+     * Empty for any non-array-element path: a record entry, a
+     * fixed-object field, a container, or the root. Backs `FieldState.key`.
      */
-    clear(path: Path): boolean;
+    arrayElementKey(path: Path): string;
+    reset(nextDefaultValues?: DeepPartial<WriteShape<F>>): void;
+    resetField(path: Path): void;
     setSchemaErrorsForPath(path: Path, errors: ValidationError[]): void;
     setAllSchemaErrors(errors: readonly ValidationError[]): void;
     clearSchemaErrors(path?: Path): void;
@@ -893,7 +921,12 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
     markFocused(path: Path, focused: boolean, meta?: {
         readonly instance?: WriteMeta['instance'];
     }): void;
-    markTouched(path: Path): void;
+    /**
+     * Flip `interacted: true` on a leaf — the sticky value-mutation flag.
+     * Driven by the directive's input listeners (via the RegisterValue's
+     * `markInteracted`); idempotent, never set by programmatic writes.
+     */
+    markInteracted(path: Path): void;
     /**
      * Walk every active-variant leaf under `segments` and flip
      * `touched: true`. Powers `form.touch(path?)`. Idempotent;
@@ -920,6 +953,22 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
      * isn't exposed to consumers.
      */
     isPristineAtPath(path: Path): boolean;
+    /**
+     * Precomputed-key shortcut for `isPristineAtPath`. The canonical
+     * key is required and must correspond to `segments`; the helper
+     * skips the `canonicalizePath` round-trip so descendant-walk loops
+     * (whose Map iteration already yields the canonical key) can read
+     * the pristine verdict without a per-leaf canonicalize.
+     */
+    isPristineAtPathByKey(key: PathKey, segments: Path): boolean;
+    /**
+     * Whether any tracked array under `path` has changed shape — a reorder,
+     * insert, or removal — relative to its construction/reset baseline. The
+     * structural half of `dirty`: per-element baselines travel with their
+     * element across a mutation, so a positional value comparison alone can
+     * no longer see the shape change.
+     */
+    hasStructuralChangeUnder(path: Path): boolean;
     getFieldRecord(path: Path): FieldRecord | undefined;
     getOriginalAtPath(path: Path): unknown;
     /**
@@ -1053,7 +1102,7 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
      * Resolved sensitive-path predicate for THIS form. Honors the
      * cascade (`useForm({ sensitiveNames })` > global default >
      * library `DEFAULT_SENSITIVE_NAMES`). Used by:
-     *  - persistence enforcement (`enforceSensitiveCheck` at write time);
+     *  - the persistence opt-in gate (`allowSensitivePersist`);
      *  - the multi-tab sync module (outbound strip + inbound reject);
      *  - DevTools edit rejection;
      *  - any future surface that needs to flag "this path holds
@@ -1064,14 +1113,6 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
      * resolved-config surface.
      */
     readonly isSensitivePath: (path: Path | PathKey | string) => boolean;
-    /**
-     * Single-segment variant of `isSensitivePath`. Used by the DevTools
-     * redact walk to short-circuit whole subtrees the moment any
-     * ancestor segment matches — saving an O(leaves × ancestors) regex
-     * sweep per timeline event. Resolved from the same `sensitiveNames`
-     * cascade as `isSensitivePath`.
-     */
-    readonly segmentMatchesSensitive: (segment: Segment) => boolean;
     /**
      * Canonical path keys explicitly opted OUT of multi-tab sync by
      * `register(path, { multiTab: false })`. The sync module's outbound
@@ -1395,6 +1436,83 @@ type InjectFormInput = {
  */
 declare function injectForm<Form extends GenericForm, GetValueFormType extends GenericForm = Form>(input?: FormKey | InjectFormInput): UseFormReturnType<Form, GetValueFormType> | null;
 
+/**
+ * Re-bind a parent's `v-register` onto an inner native element. Use
+ * inside a component that wraps a single form field whose root is
+ * NOT the input itself (e.g. a labelled-row that renders `<label>`
+ * around the input).
+ *
+ * ```vue
+ * <!-- Parent -->
+ * <MyInput v-register="form.register('email')" />
+ *
+ * <!-- MyInput.vue -->
+ * <script setup lang="ts">
+ *   import { useRegister } from 'attaform'
+ *   const rv = useRegister()
+ *   // rv.path / rv.segments / rv.formKey / rv.formInstanceId / rv.innerRef
+ *   // are all reachable directly — no `.value` unwrap.
+ * </script>
+ *
+ * <template>
+ *   <label class="field">
+ *     <span>Email</span>
+ *     <input v-register="rv" />
+ *   </label>
+ * </template>
+ * ```
+ *
+ * Returns a hybrid Proxy: it answers `__v_isRef` / `.value` like a
+ * Vue `Ref<RegisterValue | undefined>` (so templates auto-unwrap
+ * correctly and `v-register="rv"` feeds the underlying RV to the
+ * directive — preserving the directive's path-migration diff across
+ * renders), AND every other property read pierces to the captured
+ * RV's field (so `rv.path` works directly in script setup). Reads
+ * inside reactive scopes (`computed` / `watchEffect`) track the
+ * underlying `shallowRef`, so `rv.path` re-runs when the parent
+ * rebinds to a different path.
+ *
+ * Unbound state: when the parent didn't pass `v-register`, every
+ * piercing read returns `undefined` at runtime, and the return type
+ * surfaces this honestly as `UseRegisterReturn<V> | undefined`.
+ * Consumers defend with optional chaining (`rv?.formKey`,
+ * `rv?.segments`); the directive accepts `undefined` peacefully (its
+ * binding value type is already `RegisterValue<V> | undefined`), so
+ * `v-register="rv"` works whether or not a parent has bound. The
+ * composable's `onMounted` warn fires once per instance to surface
+ * the misuse case at runtime.
+ *
+ * Diagnostic: in dev mode, a single `console.warn` fires per instance
+ * at `onMounted` if the captured value is still `undefined` — by then
+ * the parent has had its full mount lifecycle to bind, so a missing
+ * binding is conclusive misuse. The warn does NOT fire on every read
+ * of the proxy, and is intentionally silent under SSR
+ * (`renderToString` skips `onMounted`); the CSR hydration pass
+ * surfaces the same diagnostic without double-counting through Nuxt's
+ * `dev:ssr-logs` channel.
+ *
+ * When the wrapper's root IS the input itself, Vue's attribute
+ * fallthrough handles the binding and `useRegister` is unnecessary.
+ * For wrappers that bind multiple fields (compound forms), use
+ * `injectForm<Form>(key?)` and call `ctx.register(...)` directly.
+ */
+
+/**
+ * Return type of `useRegister()`. Hybrid of `RegisterValue<V>` (so
+ * `rv.path` / `rv.segments` / `rv.formKey` etc. work directly in
+ * script setup) and `Ref<RegisterValue<V> | undefined>` (so Vue's
+ * template auto-unwrap surfaces the underlying RV to `v-register`
+ * and the directive's path-migration diff sees the real RV across
+ * renders).
+ *
+ * The two surfaces don't clash at the type level: `RegisterValue`
+ * doesn't carry a `value` field, and `Ref<T>`'s `value: T` becomes
+ * the hybrid's only `.value`. Older code that read `rv.value?.path`
+ * keeps working; new code can write `rv.path` directly.
+ */
+type UseRegisterReturn<V = unknown> = RegisterValue<V> & Ref<RegisterValue<V> | undefined>;
+declare function useRegister<V = unknown>(): UseRegisterReturn<V> | undefined;
+
 /**
  * Multistep-form orchestrator built around an ordered list of step slots.
  * Each slot resolves to a participating form: an existing `useForm`
@@ -1510,83 +1628,6 @@ declare function injectWizard(input?: string | InjectWizardInput): UseWizardRetu
  */
 declare function lazy<Ctx = WizardCtx>(resolve: (ctx: Ctx) => AnyForm | string | undefined): LazyMarker<Ctx>;
 
-/**
- * Re-bind a parent's `v-register` onto an inner native element. Use
- * inside a component that wraps a single form field whose root is
- * NOT the input itself (e.g. a labelled-row that renders `<label>`
- * around the input).
- *
- * ```vue
- * <!-- Parent -->
- * <MyInput v-register="form.register('email')" />
- *
- * <!-- MyInput.vue -->
- * <script setup lang="ts">
- *   import { useRegister } from 'attaform'
- *   const rv = useRegister()
- *   // rv.path / rv.segments / rv.formKey / rv.formInstanceId / rv.innerRef
- *   // are all reachable directly — no `.value` unwrap.
- * </script>
- *
- * <template>
- *   <label class="field">
- *     <span>Email</span>
- *     <input v-register="rv" />
- *   </label>
- * </template>
- * ```
- *
- * Returns a hybrid Proxy: it answers `__v_isRef` / `.value` like a
- * Vue `Ref<RegisterValue | undefined>` (so templates auto-unwrap
- * correctly and `v-register="rv"` feeds the underlying RV to the
- * directive — preserving the directive's path-migration diff across
- * renders), AND every other property read pierces to the captured
- * RV's field (so `rv.path` works directly in script setup). Reads
- * inside reactive scopes (`computed` / `watchEffect`) track the
- * underlying `shallowRef`, so `rv.path` re-runs when the parent
- * rebinds to a different path.
- *
- * Unbound state: when the parent didn't pass `v-register`, every
- * piercing read returns `undefined` at runtime, and the return type
- * surfaces this honestly as `UseRegisterReturn<V> | undefined`.
- * Consumers defend with optional chaining (`rv?.formKey`,
- * `rv?.segments`); the directive accepts `undefined` peacefully (its
- * binding value type is already `RegisterValue<V> | undefined`), so
- * `v-register="rv"` works whether or not a parent has bound. The
- * composable's `onMounted` warn fires once per instance to surface
- * the misuse case at runtime.
- *
- * Diagnostic: in dev mode, a single `console.warn` fires per instance
- * at `onMounted` if the captured value is still `undefined` — by then
- * the parent has had its full mount lifecycle to bind, so a missing
- * binding is conclusive misuse. The warn does NOT fire on every read
- * of the proxy, and is intentionally silent under SSR
- * (`renderToString` skips `onMounted`); the CSR hydration pass
- * surfaces the same diagnostic without double-counting through Nuxt's
- * `dev:ssr-logs` channel.
- *
- * When the wrapper's root IS the input itself, Vue's attribute
- * fallthrough handles the binding and `useRegister` is unnecessary.
- * For wrappers that bind multiple fields (compound forms), use
- * `injectForm<Form>(key?)` and call `ctx.register(...)` directly.
- */
-
-/**
- * Return type of `useRegister()`. Hybrid of `RegisterValue<V>` (so
- * `rv.path` / `rv.segments` / `rv.formKey` etc. work directly in
- * script setup) and `Ref<RegisterValue<V> | undefined>` (so Vue's
- * template auto-unwrap surfaces the underlying RV to `v-register`
- * and the directive's path-migration diff sees the real RV across
- * renders).
- *
- * The two surfaces don't clash at the type level: `RegisterValue`
- * doesn't carry a `value` field, and `Ref<T>`'s `value: T` becomes
- * the hybrid's only `.value`. Older code that read `rv.value?.path`
- * keeps working; new code can write `rv.path` directly.
- */
-type UseRegisterReturn<V = unknown> = RegisterValue<V> & Ref<RegisterValue<V> | undefined>;
-declare function useRegister<V = unknown>(): UseRegisterReturn<V> | undefined;
-
 /**
  * Stable identifiers for library-emitted `ValidationError` codes.
  *
@@ -1647,5 +1688,5 @@ declare const AttaformErrorCode: {
 };
 type AttaformErrorCode = (typeof AttaformErrorCode)[keyof typeof AttaformErrorCode];
 
-export { AttaformErrorCode as b, createRegistry as p, defaultCoercionRules as q, defineCoercion as r, getRegistryFromApp as s, injectForm as t, injectWizard as u, kAttaformRegistry as v, lazy as w, useRegister as x, useRegistry as y, useWizard as z };
-export type { AggregateError as A, CompiledStep as C, FormStatus as F, InjectWizardInput as I, LazyMarker as L, SSRDetectOptions as S, UseRegisterReturn as U, WizardCtx as W, AnyForm as a, AttaformRegistry as c, SerializedFormData as d, StepSlot as e, UseWizardReturnType as f, WizardCtxForm as g, WizardOnError as h, WizardOnSubmit as i, WizardOptions as j, WizardPersistFn as k, WizardRestoreFn as l, WizardRestoreState as m, WizardStatusesProxy as n, WizardSubmitContext as o };
+export { AttaformErrorCode as a, createRegistry as p, defaultCoercionRules as q, defineCoercion as r, getRegistryFromApp as s, injectForm as t, injectWizard as u, kAttaformRegistry as v, lazy as w, useRegister as x, useRegistry as y, useWizard as z };
+export type { AnyForm as A, CompiledStep as C, FormStatus as F, InjectWizardInput as I, LazyMarker as L, SSRDetectOptions as S, UseRegisterReturn as U, WizardAggregateError as W, AttaformRegistry as b, SerializedFormData as c, StepSlot as d, UseWizardReturnType as e, WizardCtx as f, WizardCtxForm as g, WizardOnError as h, WizardOnSubmit as i, WizardOptions as j, WizardPersistFn as k, WizardRestoreFn as l, WizardRestoreState as m, WizardStatusesProxy as n, WizardSubmitContext as o };