attaform 0.18.2 → 0.19.0

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { Plugin, App } from 'vue';
-import { S as SSRDetectOptions, d as SerializedFormData, c as AttaformRegistry } from './shared/attaform.CGX1CNpz.js';
-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.CGX1CNpz.js';
-import { f as AttaformDefaults, s as FormKey, G as GenericForm, ai as UseFormConfiguration, A as AbstractSchema, j as DefaultValuesInput, aj as UseFormReturnType, a6 as RegisterValue, a1 as RegisterModelDynamicCustomDirective, a8 as Segment, ac as ShouldShowErrors, am as ValidationError, c as ApiErrorEnvelope, a as ApiErrorDetails } from './shared/attaform.Ca5_6Ky-.js';
-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, E as ErrorsProxyShape, F as FieldMetaPayload, m as FieldState, n as FieldStateMap, o as FieldStateMapEntry, p as FlatPath, q as FormErrorRecord, r as FormErrorsSurface, t as FormMeta, u as FormStorage, v as FormStorageKind, H as HandleSubmit, w as HistoryConfig, I as IsTuple, x as IsUnion, J as JoinSegments, K as KeyofUnion, L as LiftedValueShape, M as MetaTrackerValue, N as NestedReadType, y as NestedType, O as OnError, z as OnInvalidSubmitPolicy, B as OnSubmit, P as PartialFlatPath, Q as Path, R as PathKey, S as PendingValidationStatus, T as PersistConfig, U as PersistConfigOptions, V as PersistIncludeMode, X as Primitive, Y as ROOT_PATH, Z as ROOT_PATH_KEY, _ as ReactiveValidationStatus, $ as RegisterDirective, a0 as RegisterFlatPath, a2 as RegisterOptions, a3 as RegisterSelectModifier, a4 as RegisterTextModifier, a5 as RegisterTransform, a9 as SetValueCallback, aa as SetValuePayload, ab as SettledValidationStatus, ad as ShouldShowErrorsConfig, 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.Ca5_6Ky-.js';
+import { S as SSRDetectOptions, d as SerializedFormData, c as AttaformRegistry } from './shared/attaform.BTpuvGec.js';
+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.BTpuvGec.js';
+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.js';
+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.js';
 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.js';
 
 /**
@@ -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.mjs

@@ -1,8 +1,8 @@
-import { i as canonicalizePath, I as InvalidPathError } from './shared/attaform.CDmaxrt2.mjs';
-export { A as AnonPersistError, a as AttaformError, D as DEFAULT_SENSITIVE_NAMES, c as InvalidUseFormConfigError, O as OutsideSetupError, R as ROOT_PATH, d as ROOT_PATH_KEY, e as RegistryNotInstalledError, f as ReservedFormKeyError, S as SensitivePersistFieldError, g as SubmitErrorHandlerError, h as assignKey, l as createAttaform, o as createRegistry, s as getRegistryFromApp, t as isPathPrefix, u as isRegisterValue, x as kAttaformRegistry, C as parseDottedPath, J as useRegister, K as useRegistry, L as vRegister } from './shared/attaform.CDmaxrt2.mjs';
-export { D as DEVTOOLS_WINDOW_KEY, R as REDACTED, h as hydrateAttaformState, r as redactSensitiveLeaves, a as renderAttaformState } from './shared/attaform.Dl161U6E.mjs';
-import { n as normalizeNumericOption } from './shared/attaform.CZ-XtZt_.mjs';
-export { A as AttaformErrorCode, d as defaultCoercionRules, a as defaultShouldShowErrors, b as defineCoercion, i as injectForm, c as injectWizard, f as isUnset, l as lazy, u as unset, k as useForm, m as useWizard } from './shared/attaform.CZ-XtZt_.mjs';
+import { i as canonicalizePath, I as InvalidPathError } from './shared/attaform.CrpjyXdO.mjs';
+export { A as AnonPersistError, a as AttaformError, D as DEFAULT_SENSITIVE_NAMES, c as InvalidUseFormConfigError, O as OutsideSetupError, R as ROOT_PATH, d as ROOT_PATH_KEY, e as RegistryNotInstalledError, f as ReservedFormKeyError, S as SensitivePersistFieldError, g as SubmitErrorHandlerError, h as assignKey, l as createAttaform, o as createRegistry, s as getRegistryFromApp, t as isPathPrefix, u as isRegisterValue, x as kAttaformRegistry, C as parseDottedPath, J as useRegister, K as useRegistry, L as vRegister } from './shared/attaform.CrpjyXdO.mjs';
+export { D as DEVTOOLS_WINDOW_KEY, R as REDACTED, h as hydrateAttaformState, r as redactSensitiveLeaves, a as renderAttaformState } from './shared/attaform.Cghpuav8.mjs';
+import { n as normalizeNumericOption } from './shared/attaform.BTi-PsHr.mjs';
+export { A as AttaformErrorCode, d as defaultCoercionRules, a as defaultDisplayState, b as defineCoercion, i as injectForm, c as injectWizard, f as isUnset, l as lazy, u as unset, k as useForm, m as useWizard } from './shared/attaform.BTi-PsHr.mjs';
 
 function escapeForInlineScript(json) {
   return json.replace(/[<>&\u2028\u2029]/g, (char) => {

package/dist/nuxt.d.cts

@@ -1,5 +1,5 @@
 import * as _nuxt_schema from '@nuxt/schema';
-import { f as AttaformDefaults } from './shared/attaform.Ca5_6Ky-.cjs';
+import { f as AttaformDefaults } from './shared/attaform.C0uGZQ4M.cjs';
 import 'vue';
 
 /**

package/dist/nuxt.d.mts

@@ -1,5 +1,5 @@
 import * as _nuxt_schema from '@nuxt/schema';
-import { f as AttaformDefaults } from './shared/attaform.Ca5_6Ky-.mjs';
+import { f as AttaformDefaults } from './shared/attaform.C0uGZQ4M.mjs';
 import 'vue';
 
 /**

package/dist/nuxt.d.ts

@@ -1,5 +1,5 @@
 import * as _nuxt_schema from '@nuxt/schema';
-import { f as AttaformDefaults } from './shared/attaform.Ca5_6Ky-.js';
+import { f as AttaformDefaults } from './shared/attaform.C0uGZQ4M.js';
 import 'vue';
 
 /**

package/dist/runtime/plugins/attaform.cjs

@@ -1,8 +1,8 @@
 'use strict';
 
 const app = require('nuxt/app');
-const devtoolsShared = require('../../shared/attaform.5UhpSVFI.cjs');
-const paths = require('../../shared/attaform.BqK_L4gK.cjs');
+const devtoolsShared = require('../../shared/attaform.CoxJ8Qm8.cjs');
+const paths = require('../../shared/attaform.BqEfHpVB.cjs');
 
 var attaform_default = app.defineNuxtPlugin({
   // `enforce: 'pre'` makes the "we run before any component's setup" claim

package/dist/runtime/plugins/attaform.mjs

@@ -1,6 +1,6 @@
 import { defineNuxtPlugin, useRuntimeConfig, useRoute } from 'nuxt/app';
-import { a as renderAttaformState, h as hydrateAttaformState, D as DEVTOOLS_WINDOW_KEY } from '../../shared/attaform.Dl161U6E.mjs';
-import { l as createAttaform, y as kAttaformWizardActiveStepResolver, s as getRegistryFromApp } from '../../shared/attaform.CDmaxrt2.mjs';
+import { a as renderAttaformState, h as hydrateAttaformState, D as DEVTOOLS_WINDOW_KEY } from '../../shared/attaform.Cghpuav8.mjs';
+import { l as createAttaform, y as kAttaformWizardActiveStepResolver, s as getRegistryFromApp } from '../../shared/attaform.CrpjyXdO.mjs';
 
 var attaform_default = defineNuxtPlugin({
   // `enforce: 'pre'` makes the "we run before any component's setup" claim