attaform 0.18.1 → 0.19.0

package/README.md

@@ -4,6 +4,7 @@
 [![npm downloads][npm-downloads-src]][npm-downloads-href]
 [![License][license-src]][license-href]
 [![Node.js Test Suite](https://github.com/attaform/attaform/actions/workflows/matrix.yml/badge.svg)](https://github.com/attaform/attaform/actions/workflows/matrix.yml)
+[![OpenSSF Scorecard][scorecard-src]][scorecard-href]
 [![Nuxt][nuxt-src]][nuxt-href]
 
 A type-safe, schema-driven form library for Vue 3 and Nuxt with first-class Zod support.
@@ -192,5 +193,7 @@ MIT; see [LICENSE](./LICENSE).
 [npm-downloads-href]: https://npm.chart.dev/attaform
 [license-src]: https://img.shields.io/npm/l/attaform.svg?style=flat&colorA=020420&colorB=00DC82
 [license-href]: https://npmjs.com/package/attaform
+[scorecard-src]: https://img.shields.io/ossf-scorecard/github.com/attaform/Attaform?label=OpenSSF%20Scorecard&style=flat&colorA=020420&colorB=00DC82
+[scorecard-href]: https://securityscorecards.dev/viewer/?uri=github.com/attaform/Attaform
 [nuxt-src]: https://img.shields.io/badge/Nuxt-020420?logo=nuxt.js
 [nuxt-href]: https://nuxt.com

package/dist/chunks/devtools.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-const paths = require('../shared/attaform.BqK_L4gK.cjs');
+const paths = require('../shared/attaform.BqEfHpVB.cjs');
 
 const INSPECTOR_ID = "attaform";
 const TIMELINE_LAYER_ID = "attaform:events";

package/dist/chunks/devtools.mjs

@@ -1,4 +1,4 @@
-import { a as canonicalizePath } from '../shared/attaform.Xhg0AYNa.mjs';
+import { i as canonicalizePath } from '../shared/attaform.CrpjyXdO.mjs';
 
 const INSPECTOR_ID = "attaform";
 const TIMELINE_LAYER_ID = "attaform:events";

package/dist/chunks/indexeddb.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-const paths = require('../shared/attaform.BqK_L4gK.cjs');
+const paths = require('../shared/attaform.BqEfHpVB.cjs');
 
 const DB_NAME = "attaform";
 const STORE_NAME = "kv";

package/dist/chunks/indexeddb.mjs

@@ -1,4 +1,4 @@
-import { _ as __DEV__ } from '../shared/attaform.Xhg0AYNa.mjs';
+import { _ as __DEV__ } from '../shared/attaform.CrpjyXdO.mjs';
 
 const DB_NAME = "attaform";
 const STORE_NAME = "kv";

package/dist/chunks/local-storage.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-const paths = require('../shared/attaform.BqK_L4gK.cjs');
+const paths = require('../shared/attaform.BqEfHpVB.cjs');
 
 function createLocalStorageAdapter() {
   const available = typeof localStorage !== "undefined";

package/dist/chunks/local-storage.mjs

@@ -1,4 +1,4 @@
-import { _ as __DEV__ } from '../shared/attaform.Xhg0AYNa.mjs';
+import { _ as __DEV__ } from '../shared/attaform.CrpjyXdO.mjs';
 
 function createLocalStorageAdapter() {
   const available = typeof localStorage !== "undefined";

package/dist/chunks/session-storage.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-const paths = require('../shared/attaform.BqK_L4gK.cjs');
+const paths = require('../shared/attaform.BqEfHpVB.cjs');
 
 function createSessionStorageAdapter() {
   const available = typeof sessionStorage !== "undefined";

package/dist/chunks/session-storage.mjs

@@ -1,4 +1,4 @@
-import { _ as __DEV__ } from '../shared/attaform.Xhg0AYNa.mjs';
+import { _ as __DEV__ } from '../shared/attaform.CrpjyXdO.mjs';
 
 function createSessionStorageAdapter() {
   const available = typeof sessionStorage !== "undefined";

package/dist/index.cjs

@@ -1,8 +1,8 @@
 'use strict';
 
-const paths = require('./shared/attaform.BqK_L4gK.cjs');
-const devtoolsShared = require('./shared/attaform.5UhpSVFI.cjs');
-const injectWizard = require('./shared/attaform.II89Pcf4.cjs');
+const paths = require('./shared/attaform.BqEfHpVB.cjs');
+const devtoolsShared = require('./shared/attaform.CoxJ8Qm8.cjs');
+const injectWizard = require('./shared/attaform.C1msmO2v.cjs');
 
 function escapeForInlineScript(json) {
   return json.replace(/[<>&\u2028\u2029]/g, (char) => {
@@ -185,7 +185,7 @@ exports.redactSensitiveLeaves = devtoolsShared.redactSensitiveLeaves;
 exports.renderAttaformState = devtoolsShared.renderAttaformState;
 exports.AttaformErrorCode = injectWizard.AttaformErrorCode;
 exports.defaultCoercionRules = injectWizard.defaultCoercionRules;
-exports.defaultShouldShowErrors = injectWizard.defaultShouldShowErrors;
+exports.defaultDisplayState = injectWizard.defaultDisplayState;
 exports.defineCoercion = injectWizard.defineCoercion;
 exports.injectForm = injectWizard.injectForm;
 exports.injectWizard = injectWizard.injectWizard;

package/dist/index.d.cts

@@ -1,8 +1,8 @@
 import { Plugin, App } from 'vue';
-import { S as SSRDetectOptions, a as SerializedFormData, A as AttaformRegistry } from './shared/attaform.DoSuaKMd.cjs';
-export { b as AggregateError, c as AnyForm, d as AttaformErrorCode, C as CompiledStep, F as FormStatus, I as InjectWizardInput, L as LazyMarker, e as StepSlot, U as UseRegisterReturn, f as UseWizardReturnType, W as WizardCtx, g as WizardCtxForm, h as WizardOnError, i as WizardOnSubmit, j as WizardOptions, k as WizardPersistFn, l as WizardRestoreFn, m as WizardRestoreState, n as WizardStatusesProxy, o as WizardSubmitContext, p as createRegistry, q as defaultCoercionRules, r as defineCoercion, s as getRegistryFromApp, t as injectForm, u as injectWizard, v as kAttaformRegistry, w as lazy, x as useRegister, y as useRegistry, z as useWizard } from './shared/attaform.DoSuaKMd.cjs';
-import { A as AttaformDefaults, F as FormKey, G as GenericForm, U as UseFormConfiguration, a as AbstractSchema, D as DefaultValuesInput, b as UseFormReturnType, R as RegisterValue, c as RegisterModelDynamicCustomDirective, S as Segment, d as ShouldShowErrors, V as ValidationError, e as ApiErrorEnvelope, f as ApiErrorDetails } from './shared/attaform.Dj9mwbaV.cjs';
-export { g as ApiErrorEntry, h as ArrayItem, i as ArrayPath, C as CoercionEntry, j as CoercionRegistry, k as CoercionResult, l as CustomDirectiveRegisterAssignerFn, m as DeepPartial, n as DefaultValuesResponse, o as DefaultValuesShape, E as ErrorsProxyShape, p as FieldMetaPayload, q as FieldState, r as FieldStateMap, s as FieldStateMapEntry, t as FlatPath, u as FormErrorRecord, v as FormErrorsSurface, w as FormMeta, x as FormStorage, y as FormStorageKind, H as HandleSubmit, z as HistoryConfig, I as IsTuple, B as IsUnion, J as JoinSegments, K as KeyofUnion, L as LiftedValueShape, M as MetaTrackerValue, N as NestedReadType, O as NestedType, P as OnError, Q as OnInvalidSubmitPolicy, T as OnSubmit, W as PartialFlatPath, X as Path, Y as PathKey, Z as PendingValidationStatus, _ as PersistConfig, $ as PersistConfigOptions, a0 as PersistIncludeMode, a1 as Primitive, a2 as ROOT_PATH, a3 as ROOT_PATH_KEY, a4 as ReactiveValidationStatus, a5 as RegisterDirective, a6 as RegisterFlatPath, a7 as RegisterOptions, a8 as RegisterSelectModifier, a9 as RegisterTextModifier, aa as RegisterTransform, ab as SetValueCallback, ac as SetValuePayload, ad as SettledValidationStatus, ae as ShouldShowErrorsConfig, af as SlimPrimitiveKind, ag as SlimRuntimeOf, ah as SubmitHandler, ai as Unset, aj as ValidateOn, ak as ValidateOnConfig, al as ValidationResponse, am as ValidationResponseWithoutValue, an as ValueOfUnion, ao as WriteMeta, ap as WriteShape, aq as canonicalizePath, ar as isPathPrefix, as as isUnset, at as parseDottedPath, au as unset } from './shared/attaform.Dj9mwbaV.cjs';
+import { S as SSRDetectOptions, d as SerializedFormData, c as AttaformRegistry } from './shared/attaform.ePUcKxId.cjs';
+export { A as AggregateError, a as AnyForm, b as AttaformErrorCode, C as CompiledStep, F as FormStatus, I as InjectWizardInput, L as LazyMarker, e as StepSlot, U as UseRegisterReturn, f as UseWizardReturnType, W as WizardCtx, g as WizardCtxForm, h as WizardOnError, i as WizardOnSubmit, j as WizardOptions, k as WizardPersistFn, l as WizardRestoreFn, m as WizardRestoreState, n as WizardStatusesProxy, o as WizardSubmitContext, p as createRegistry, q as defaultCoercionRules, r as defineCoercion, s as getRegistryFromApp, t as injectForm, u as injectWizard, v as kAttaformRegistry, w as lazy, x as useRegister, y as useRegistry, z as useWizard } from './shared/attaform.ePUcKxId.cjs';
+import { f as AttaformDefaults, t as FormKey, G as GenericForm, ai as UseFormConfiguration, A as AbstractSchema, j as DefaultValuesInput, aj as UseFormReturnType, a8 as RegisterValue, a3 as RegisterModelDynamicCustomDirective, aa as Segment, x as GetDisplayState, am as ValidationError, c as ApiErrorEnvelope, a as ApiErrorDetails } from './shared/attaform.C0uGZQ4M.cjs';
+export { b as ApiErrorEntry, d as ArrayItem, e as ArrayPath, C as CoercionEntry, g as CoercionRegistry, h as CoercionResult, i as CustomDirectiveRegisterAssignerFn, D as DeepPartial, k as DefaultValuesResponse, l as DefaultValuesShape, m as DisplayState, E as ErrorsProxyShape, F as FieldMetaPayload, n as FieldState, o as FieldStateMap, p as FieldStateMapEntry, q as FlatPath, r as FormErrorRecord, s as FormErrorsSurface, u as FormMeta, v as FormStorage, w as FormStorageKind, H as HandleSubmit, y as HistoryConfig, I as IsTuple, z as IsUnion, J as JoinSegments, K as KeyofUnion, L as LiftedValueShape, M as MetaTrackerValue, N as NestedReadType, B as NestedType, O as OnError, P as OnInvalidSubmitPolicy, Q as OnSubmit, R as PartialFlatPath, S as Path, T as PathKey, U as PendingValidationStatus, V as PersistConfig, W as PersistConfigOptions, X as PersistIncludeMode, Z as Primitive, _ as ROOT_PATH, $ as ROOT_PATH_KEY, a0 as ReactiveValidationStatus, a1 as RegisterDirective, a2 as RegisterFlatPath, a4 as RegisterOptions, a5 as RegisterSelectModifier, a6 as RegisterTextModifier, a7 as RegisterTransform, ab as SetValueCallback, ac as SetValuePayload, ad as SettledValidationStatus, ae as SlimPrimitiveKind, af as SlimRuntimeOf, ag as SubmitHandler, ah as Unset, ak as ValidateOn, al as ValidateOnConfig, an as ValidationResponse, ao as ValidationResponseWithoutValue, ap as ValueOfUnion, aq as WriteMeta, ar as WriteShape, as as canonicalizePath, at as isPathPrefix, au as isUnset, av as parseDottedPath, aw as unset } from './shared/attaform.C0uGZQ4M.cjs';
 export { A as AnonPersistError, a as AttaformError, I as InvalidPathError, b as InvalidUseFormConfigError, O as OutsideSetupError, R as RegistryNotInstalledError, c as ReservedFormKeyError, S as SensitivePersistFieldError, d as SubmitErrorHandlerError } from './shared/attaform.B7rzpK1U.cjs';
 
 /**
@@ -287,86 +287,79 @@ declare global {
 }
 
 /**
- * Library-default heuristic for `shouldShowErrors`. Drives
- * `field.showErrors` and `form.meta.showErrors` whenever the consumer
- * has not configured an override at either the plugin or per-form
- * level.
- *
- * Four clauses: the first two are hard gates; clause 3 is an
- * aggressive override after the first submit attempt; clause 4 is
- * the pre-submit timing gate.
- *
- * 1. **Own-path filter.** The field must have at least one error whose
- *    path equals the field's own path. Leaves always satisfy this when
- *    they have errors. Containers (intermediate or root) only satisfy
- *    it for errors that point directly at them, so a UI rendering
- *    `field.showErrors` at a container never duplicates errors that a
- *    more-specific descendant will already render. Aggregate banners
- *    that want "any error anywhere passed the gate" should bind to
- *    `form.meta.errorCount > 0` (paired with whatever timing signal
- *    fits), not to `form.meta.showErrors`.
- *
- * 2. **Not currently validating.** While the field is mid-revalidation
- *    (`field.validating === true`) the verdict in `field.errors` is
- *    stale by definition. The error itself stays in the store under
- *    the stale-while-revalidate contract so the surface doesn't
- *    flicker to empty, but the UX gate hides it: the application is
- *    actively re-checking, so the message would mis-narrate the
- *    state of the world. Containers roll up `validating` as a
- *    disjunction, so any descendant under revalidation hides the
- *    container's `showErrors` too. The error returns the moment the
- *    new verdict lands and `validating` flips back to false.
- *
- * 3. **Post-submit override.** Once `formMeta.submissionAttempts > 0`
- *    the heuristic surfaces every own-path error unconditionally on
- *    the field axis (subject only to the two gates above). The
- *    counter covers two distinct gestures:
- *
- *    - `form.handleSubmit` directly, or `wizard.handleSubmit` at an
- *      intermediate step. The user asked this specific form to
- *      commit; transient mid-edit hiding is no longer appropriate.
- *
- *    - `wizard.handleSubmit` at the final step. The wizard validates
- *      every form in parallel and bumps each one's `submissionAttempts`,
- *      so a `Finish`-button submission reveals errors across the
- *      whole multistep flow at once. That's the review-surface UX:
- *      by the time the user tries to commit the wizard, every
- *      blocking error lights up regardless of which step it lives on.
- *
- *    The arm deliberately covers focused, pristine, and untouched
- *    fields, so the next paint after the user tried to progress lights
- *    up every problem the validator found.
- *
- * 4. **Pre-submit timing gate.** Before the first submit attempt,
- *    show once the user has touched the field (sticky-true after the
- *    first blur) AND is not currently focused on it. The not-focused
- *    half hides transient errors while the user is actively editing
- *    the field; they reappear when the user blurs (or focuses a
- *    sibling). This deliberately includes blur-without-typing on a
- *    required field (touched flips on blur regardless of `dirty`), so
- *    a user who visits an empty required field and moves on sees the
- *    error.
- *
- * The framework already gates on `errors.length > 0` before invoking
- * the predicate, so the body only decides *when* to surface existing
- * errors, not whether errors exist.
+ * Library-default `getDisplayState` heuristic. Resolves every path's
+ * `field.displayState` — and thus `field.show*` and the `form.meta`
+ * rollups — whenever the consumer has not configured an override at the
+ * per-form or plugin level.
+ *
+ * One timing gate, then precedence:
+ *
+ * 1. **Timing gate.** `gateOpen` once the form has been submitted
+ *    (`submissionAttempts > 0`) OR the field has been edited and then
+ *    left (`blurredAfterInteraction === true`). Before the gate opens
+ *    the verdict is `'idle'` regardless of errors. This is the "reward
+ *    early, punish late" rule:
+ *      - A clean tab-through never engages. `blurredAfterInteraction`
+ *        only flips on a blur that follows an edit, so visiting a field
+ *        and moving on without editing it stays quiet until a submit
+ *        forces the issue, even if the field was tabbed through before.
+ *      - The first pass stays quiet. Editing alone (`interacted`) does
+ *        not open the gate; the error reveals only once the user
+ *        finishes that pass and leaves the field, never mid-entry.
+ *      - Recovery is live. The bit is sticky and carries no not-focused
+ *        term, so once a field has been revealed it stays open through a
+ *        re-focus: a shown error clears (or greens) the instant the
+ *        value becomes valid, without forcing another blur.
+ *
+ *    The submit arm covers `form.handleSubmit` directly and
+ *    `wizard.handleSubmit` (which bumps `submissionAttempts` on the
+ *    active form at intermediate steps and on every form at the final
+ *    step, lighting up the whole flow at once).
+ *
+ * 2. **Pending.** With the gate open, a per-field run in flight
+ *    (`validating === true`) wins: the verdict in `errors` is stale by
+ *    definition, so surface `'pending'` (a spinner) rather than a
+ *    possibly-wrong error or success. Containers roll `validating` up as
+ *    a disjunction, so any descendant under revalidation reads
+ *    `'pending'` at the container too.
+ *
+ * 3. **Error.** An own-path error (one whose path equals the field's own
+ *    path) resolves to `'error'`. The own-path filter means a container
+ *    never duplicates an error a more-specific descendant already
+ *    renders; aggregate banners bind to `form.meta.errorCount` instead.
+ *
+ * 4. **Success.** No error, `valid === true`, and the green check is
+ *    earned: the field is non-blank and `dirty` (its value diverges from
+ *    the hydration original). Gating success on `dirty && !blank` keeps
+ *    the check meaningful — an empty field that happens to pass, a
+ *    pre-filled field merely tabbed through, and the post-submit flood of
+ *    every valid field all stay `'idle'` rather than greening for free.
+ *    `valid` already gates async schemas on the form-wide first
+ *    validation pass, so success never fires before the first verdict
+ *    lands.
+ *
+ * 5. **Idle.** Anything else — gate open but not validating, no own-path
+ *    error, and either not yet `valid` or valid-but-unearned (blank or
+ *    unchanged) — stays `'idle'`.
  *
  * Public re-export so adopters can compose with this without
- * copy-pasting the rule body. A layered predicate that adds a special
- * case but otherwise defers to the library default picks up future
- * heuristic refinements automatically:
+ * copy-pasting the rule body — a layered predicate that special-cases a
+ * subtree but otherwise defers picks up future refinements
+ * automatically:
  *
  * ```ts
- * import { defaultShouldShowErrors } from 'attaform'
+ * import { defaultDisplayState } from 'attaform'
  *
  * useForm({
  *   schema,
- *   shouldShowErrors: (field, formMeta) =>
- *     field.path[0] === 'urgent' || defaultShouldShowErrors(field, formMeta),
+ *   getDisplayState: (field, formMeta) => {
+ *     const state = defaultDisplayState(field, formMeta)
+ *     return field.path[0] === 'username' && state === 'success' ? 'idle' : state
+ *   },
  * })
  * ```
  */
-declare const defaultShouldShowErrors: ShouldShowErrors;
+declare const defaultDisplayState: GetDisplayState;
 
 /**
  * The library's built-in conservative set of identifier name stems that
@@ -529,5 +522,5 @@ declare const PARSE_API_ERRORS_DEFAULTS: {
  */
 declare function parseApiErrors(payload: ApiErrorEnvelope | ApiErrorDetails | null | undefined | unknown, options: ParseApiErrorsOptions): ParseApiErrorsResult;
 
-export { AbstractSchema, ApiErrorDetails, ApiErrorEnvelope, AttaformDefaults, AttaformRegistry, DEFAULT_SENSITIVE_NAMES, DEVTOOLS_WINDOW_KEY, DefaultValuesInput, FormKey, GenericForm, PARSE_API_ERRORS_DEFAULTS, REDACTED, RegisterValue, Segment, SerializedFormData, ShouldShowErrors, UseFormConfiguration, UseFormReturnType, ValidationError, assignKey, createAttaform, defaultShouldShowErrors, escapeForInlineScript, hydrateAttaformState, isRegisterValue, parseApiErrors, redactSensitiveLeaves, renderAttaformState, useAbstractForm as useForm, vRegister };
+export { AbstractSchema, ApiErrorDetails, ApiErrorEnvelope, AttaformDefaults, AttaformRegistry, DEFAULT_SENSITIVE_NAMES, DEVTOOLS_WINDOW_KEY, DefaultValuesInput, FormKey, GenericForm, GetDisplayState, PARSE_API_ERRORS_DEFAULTS, REDACTED, RegisterValue, Segment, SerializedFormData, UseFormConfiguration, UseFormReturnType, ValidationError, assignKey, createAttaform, defaultDisplayState, escapeForInlineScript, hydrateAttaformState, isRegisterValue, parseApiErrors, redactSensitiveLeaves, renderAttaformState, useAbstractForm as useForm, vRegister };
 export type { AttaformDevtoolsBridge, AttaformPluginOptions, ParseApiErrorsOptions, ParseApiErrorsResult, SerializedAttaformState };

package/dist/index.d.mts

@@ -1,8 +1,8 @@
 import { Plugin, App } from 'vue';
-import { S as SSRDetectOptions, a as SerializedFormData, A as AttaformRegistry } from './shared/attaform.iTqxvl-P.mjs';
-export { b as AggregateError, c as AnyForm, d as AttaformErrorCode, C as CompiledStep, F as FormStatus, I as InjectWizardInput, L as LazyMarker, e as StepSlot, U as UseRegisterReturn, f as UseWizardReturnType, W as WizardCtx, g as WizardCtxForm, h as WizardOnError, i as WizardOnSubmit, j as WizardOptions, k as WizardPersistFn, l as WizardRestoreFn, m as WizardRestoreState, n as WizardStatusesProxy, o as WizardSubmitContext, p as createRegistry, q as defaultCoercionRules, r as defineCoercion, s as getRegistryFromApp, t as injectForm, u as injectWizard, v as kAttaformRegistry, w as lazy, x as useRegister, y as useRegistry, z as useWizard } from './shared/attaform.iTqxvl-P.mjs';
-import { A as AttaformDefaults, F as FormKey, G as GenericForm, U as UseFormConfiguration, a as AbstractSchema, D as DefaultValuesInput, b as UseFormReturnType, R as RegisterValue, c as RegisterModelDynamicCustomDirective, S as Segment, d as ShouldShowErrors, V as ValidationError, e as ApiErrorEnvelope, f as ApiErrorDetails } from './shared/attaform.Dj9mwbaV.mjs';
-export { g as ApiErrorEntry, h as ArrayItem, i as ArrayPath, C as CoercionEntry, j as CoercionRegistry, k as CoercionResult, l as CustomDirectiveRegisterAssignerFn, m as DeepPartial, n as DefaultValuesResponse, o as DefaultValuesShape, E as ErrorsProxyShape, p as FieldMetaPayload, q as FieldState, r as FieldStateMap, s as FieldStateMapEntry, t as FlatPath, u as FormErrorRecord, v as FormErrorsSurface, w as FormMeta, x as FormStorage, y as FormStorageKind, H as HandleSubmit, z as HistoryConfig, I as IsTuple, B as IsUnion, J as JoinSegments, K as KeyofUnion, L as LiftedValueShape, M as MetaTrackerValue, N as NestedReadType, O as NestedType, P as OnError, Q as OnInvalidSubmitPolicy, T as OnSubmit, W as PartialFlatPath, X as Path, Y as PathKey, Z as PendingValidationStatus, _ as PersistConfig, $ as PersistConfigOptions, a0 as PersistIncludeMode, a1 as Primitive, a2 as ROOT_PATH, a3 as ROOT_PATH_KEY, a4 as ReactiveValidationStatus, a5 as RegisterDirective, a6 as RegisterFlatPath, a7 as RegisterOptions, a8 as RegisterSelectModifier, a9 as RegisterTextModifier, aa as RegisterTransform, ab as SetValueCallback, ac as SetValuePayload, ad as SettledValidationStatus, ae as ShouldShowErrorsConfig, af as SlimPrimitiveKind, ag as SlimRuntimeOf, ah as SubmitHandler, ai as Unset, aj as ValidateOn, ak as ValidateOnConfig, al as ValidationResponse, am as ValidationResponseWithoutValue, an as ValueOfUnion, ao as WriteMeta, ap as WriteShape, aq as canonicalizePath, ar as isPathPrefix, as as isUnset, at as parseDottedPath, au as unset } from './shared/attaform.Dj9mwbaV.mjs';
+import { S as SSRDetectOptions, d as SerializedFormData, c as AttaformRegistry } from './shared/attaform.BtBmfLQN.mjs';
+export { A as AggregateError, a as AnyForm, b as AttaformErrorCode, C as CompiledStep, F as FormStatus, I as InjectWizardInput, L as LazyMarker, e as StepSlot, U as UseRegisterReturn, f as UseWizardReturnType, W as WizardCtx, g as WizardCtxForm, h as WizardOnError, i as WizardOnSubmit, j as WizardOptions, k as WizardPersistFn, l as WizardRestoreFn, m as WizardRestoreState, n as WizardStatusesProxy, o as WizardSubmitContext, p as createRegistry, q as defaultCoercionRules, r as defineCoercion, s as getRegistryFromApp, t as injectForm, u as injectWizard, v as kAttaformRegistry, w as lazy, x as useRegister, y as useRegistry, z as useWizard } from './shared/attaform.BtBmfLQN.mjs';
+import { f as AttaformDefaults, t as FormKey, G as GenericForm, ai as UseFormConfiguration, A as AbstractSchema, j as DefaultValuesInput, aj as UseFormReturnType, a8 as RegisterValue, a3 as RegisterModelDynamicCustomDirective, aa as Segment, x as GetDisplayState, am as ValidationError, c as ApiErrorEnvelope, a as ApiErrorDetails } from './shared/attaform.C0uGZQ4M.mjs';
+export { b as ApiErrorEntry, d as ArrayItem, e as ArrayPath, C as CoercionEntry, g as CoercionRegistry, h as CoercionResult, i as CustomDirectiveRegisterAssignerFn, D as DeepPartial, k as DefaultValuesResponse, l as DefaultValuesShape, m as DisplayState, E as ErrorsProxyShape, F as FieldMetaPayload, n as FieldState, o as FieldStateMap, p as FieldStateMapEntry, q as FlatPath, r as FormErrorRecord, s as FormErrorsSurface, u as FormMeta, v as FormStorage, w as FormStorageKind, H as HandleSubmit, y as HistoryConfig, I as IsTuple, z as IsUnion, J as JoinSegments, K as KeyofUnion, L as LiftedValueShape, M as MetaTrackerValue, N as NestedReadType, B as NestedType, O as OnError, P as OnInvalidSubmitPolicy, Q as OnSubmit, R as PartialFlatPath, S as Path, T as PathKey, U as PendingValidationStatus, V as PersistConfig, W as PersistConfigOptions, X as PersistIncludeMode, Z as Primitive, _ as ROOT_PATH, $ as ROOT_PATH_KEY, a0 as ReactiveValidationStatus, a1 as RegisterDirective, a2 as RegisterFlatPath, a4 as RegisterOptions, a5 as RegisterSelectModifier, a6 as RegisterTextModifier, a7 as RegisterTransform, ab as SetValueCallback, ac as SetValuePayload, ad as SettledValidationStatus, ae as SlimPrimitiveKind, af as SlimRuntimeOf, ag as SubmitHandler, ah as Unset, ak as ValidateOn, al as ValidateOnConfig, an as ValidationResponse, ao as ValidationResponseWithoutValue, ap as ValueOfUnion, aq as WriteMeta, ar as WriteShape, as as canonicalizePath, at as isPathPrefix, au as isUnset, av as parseDottedPath, aw as unset } from './shared/attaform.C0uGZQ4M.mjs';
 export { A as AnonPersistError, a as AttaformError, I as InvalidPathError, b as InvalidUseFormConfigError, O as OutsideSetupError, R as RegistryNotInstalledError, c as ReservedFormKeyError, S as SensitivePersistFieldError, d as SubmitErrorHandlerError } from './shared/attaform.B7rzpK1U.mjs';
 
 /**
@@ -287,86 +287,79 @@ declare global {
 }
 
 /**
- * Library-default heuristic for `shouldShowErrors`. Drives
- * `field.showErrors` and `form.meta.showErrors` whenever the consumer
- * has not configured an override at either the plugin or per-form
- * level.
- *
- * Four clauses: the first two are hard gates; clause 3 is an
- * aggressive override after the first submit attempt; clause 4 is
- * the pre-submit timing gate.
- *
- * 1. **Own-path filter.** The field must have at least one error whose
- *    path equals the field's own path. Leaves always satisfy this when
- *    they have errors. Containers (intermediate or root) only satisfy
- *    it for errors that point directly at them, so a UI rendering
- *    `field.showErrors` at a container never duplicates errors that a
- *    more-specific descendant will already render. Aggregate banners
- *    that want "any error anywhere passed the gate" should bind to
- *    `form.meta.errorCount > 0` (paired with whatever timing signal
- *    fits), not to `form.meta.showErrors`.
- *
- * 2. **Not currently validating.** While the field is mid-revalidation
- *    (`field.validating === true`) the verdict in `field.errors` is
- *    stale by definition. The error itself stays in the store under
- *    the stale-while-revalidate contract so the surface doesn't
- *    flicker to empty, but the UX gate hides it: the application is
- *    actively re-checking, so the message would mis-narrate the
- *    state of the world. Containers roll up `validating` as a
- *    disjunction, so any descendant under revalidation hides the
- *    container's `showErrors` too. The error returns the moment the
- *    new verdict lands and `validating` flips back to false.
- *
- * 3. **Post-submit override.** Once `formMeta.submissionAttempts > 0`
- *    the heuristic surfaces every own-path error unconditionally on
- *    the field axis (subject only to the two gates above). The
- *    counter covers two distinct gestures:
- *
- *    - `form.handleSubmit` directly, or `wizard.handleSubmit` at an
- *      intermediate step. The user asked this specific form to
- *      commit; transient mid-edit hiding is no longer appropriate.
- *
- *    - `wizard.handleSubmit` at the final step. The wizard validates
- *      every form in parallel and bumps each one's `submissionAttempts`,
- *      so a `Finish`-button submission reveals errors across the
- *      whole multistep flow at once. That's the review-surface UX:
- *      by the time the user tries to commit the wizard, every
- *      blocking error lights up regardless of which step it lives on.
- *
- *    The arm deliberately covers focused, pristine, and untouched
- *    fields, so the next paint after the user tried to progress lights
- *    up every problem the validator found.
- *
- * 4. **Pre-submit timing gate.** Before the first submit attempt,
- *    show once the user has touched the field (sticky-true after the
- *    first blur) AND is not currently focused on it. The not-focused
- *    half hides transient errors while the user is actively editing
- *    the field; they reappear when the user blurs (or focuses a
- *    sibling). This deliberately includes blur-without-typing on a
- *    required field (touched flips on blur regardless of `dirty`), so
- *    a user who visits an empty required field and moves on sees the
- *    error.
- *
- * The framework already gates on `errors.length > 0` before invoking
- * the predicate, so the body only decides *when* to surface existing
- * errors, not whether errors exist.
+ * Library-default `getDisplayState` heuristic. Resolves every path's
+ * `field.displayState` — and thus `field.show*` and the `form.meta`
+ * rollups — whenever the consumer has not configured an override at the
+ * per-form or plugin level.
+ *
+ * One timing gate, then precedence:
+ *
+ * 1. **Timing gate.** `gateOpen` once the form has been submitted
+ *    (`submissionAttempts > 0`) OR the field has been edited and then
+ *    left (`blurredAfterInteraction === true`). Before the gate opens
+ *    the verdict is `'idle'` regardless of errors. This is the "reward
+ *    early, punish late" rule:
+ *      - A clean tab-through never engages. `blurredAfterInteraction`
+ *        only flips on a blur that follows an edit, so visiting a field
+ *        and moving on without editing it stays quiet until a submit
+ *        forces the issue, even if the field was tabbed through before.
+ *      - The first pass stays quiet. Editing alone (`interacted`) does
+ *        not open the gate; the error reveals only once the user
+ *        finishes that pass and leaves the field, never mid-entry.
+ *      - Recovery is live. The bit is sticky and carries no not-focused
+ *        term, so once a field has been revealed it stays open through a
+ *        re-focus: a shown error clears (or greens) the instant the
+ *        value becomes valid, without forcing another blur.
+ *
+ *    The submit arm covers `form.handleSubmit` directly and
+ *    `wizard.handleSubmit` (which bumps `submissionAttempts` on the
+ *    active form at intermediate steps and on every form at the final
+ *    step, lighting up the whole flow at once).
+ *
+ * 2. **Pending.** With the gate open, a per-field run in flight
+ *    (`validating === true`) wins: the verdict in `errors` is stale by
+ *    definition, so surface `'pending'` (a spinner) rather than a
+ *    possibly-wrong error or success. Containers roll `validating` up as
+ *    a disjunction, so any descendant under revalidation reads
+ *    `'pending'` at the container too.
+ *
+ * 3. **Error.** An own-path error (one whose path equals the field's own
+ *    path) resolves to `'error'`. The own-path filter means a container
+ *    never duplicates an error a more-specific descendant already
+ *    renders; aggregate banners bind to `form.meta.errorCount` instead.
+ *
+ * 4. **Success.** No error, `valid === true`, and the green check is
+ *    earned: the field is non-blank and `dirty` (its value diverges from
+ *    the hydration original). Gating success on `dirty && !blank` keeps
+ *    the check meaningful — an empty field that happens to pass, a
+ *    pre-filled field merely tabbed through, and the post-submit flood of
+ *    every valid field all stay `'idle'` rather than greening for free.
+ *    `valid` already gates async schemas on the form-wide first
+ *    validation pass, so success never fires before the first verdict
+ *    lands.
+ *
+ * 5. **Idle.** Anything else — gate open but not validating, no own-path
+ *    error, and either not yet `valid` or valid-but-unearned (blank or
+ *    unchanged) — stays `'idle'`.
  *
  * Public re-export so adopters can compose with this without
- * copy-pasting the rule body. A layered predicate that adds a special
- * case but otherwise defers to the library default picks up future
- * heuristic refinements automatically:
+ * copy-pasting the rule body — a layered predicate that special-cases a
+ * subtree but otherwise defers picks up future refinements
+ * automatically:
  *
  * ```ts
- * import { defaultShouldShowErrors } from 'attaform'
+ * import { defaultDisplayState } from 'attaform'
  *
  * useForm({
  *   schema,
- *   shouldShowErrors: (field, formMeta) =>
- *     field.path[0] === 'urgent' || defaultShouldShowErrors(field, formMeta),
+ *   getDisplayState: (field, formMeta) => {
+ *     const state = defaultDisplayState(field, formMeta)
+ *     return field.path[0] === 'username' && state === 'success' ? 'idle' : state
+ *   },
  * })
  * ```
  */
-declare const defaultShouldShowErrors: ShouldShowErrors;
+declare const defaultDisplayState: GetDisplayState;
 
 /**
  * The library's built-in conservative set of identifier name stems that
@@ -529,5 +522,5 @@ declare const PARSE_API_ERRORS_DEFAULTS: {
  */
 declare function parseApiErrors(payload: ApiErrorEnvelope | ApiErrorDetails | null | undefined | unknown, options: ParseApiErrorsOptions): ParseApiErrorsResult;
 
-export { AbstractSchema, ApiErrorDetails, ApiErrorEnvelope, AttaformDefaults, AttaformRegistry, DEFAULT_SENSITIVE_NAMES, DEVTOOLS_WINDOW_KEY, DefaultValuesInput, FormKey, GenericForm, PARSE_API_ERRORS_DEFAULTS, REDACTED, RegisterValue, Segment, SerializedFormData, ShouldShowErrors, UseFormConfiguration, UseFormReturnType, ValidationError, assignKey, createAttaform, defaultShouldShowErrors, escapeForInlineScript, hydrateAttaformState, isRegisterValue, parseApiErrors, redactSensitiveLeaves, renderAttaformState, useAbstractForm as useForm, vRegister };
+export { AbstractSchema, ApiErrorDetails, ApiErrorEnvelope, AttaformDefaults, AttaformRegistry, DEFAULT_SENSITIVE_NAMES, DEVTOOLS_WINDOW_KEY, DefaultValuesInput, FormKey, GenericForm, GetDisplayState, PARSE_API_ERRORS_DEFAULTS, REDACTED, RegisterValue, Segment, SerializedFormData, UseFormConfiguration, UseFormReturnType, ValidationError, assignKey, createAttaform, defaultDisplayState, escapeForInlineScript, hydrateAttaformState, isRegisterValue, parseApiErrors, redactSensitiveLeaves, renderAttaformState, useAbstractForm as useForm, vRegister };
 export type { AttaformDevtoolsBridge, AttaformPluginOptions, ParseApiErrorsOptions, ParseApiErrorsResult, SerializedAttaformState };