attaform 0.19.0 → 0.20.1

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

@@ -1,4 +1,4 @@
-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, aa as Segment, f as AttaformDefaults, aj as UseFormReturnType, a8 as RegisterValue } from './attaform.C0uGZQ4M.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;
@@ -701,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
@@ -797,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
@@ -852,14 +869,6 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
     arrayElementKey(path: Path): string;
     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))`.
-     */
-    clear(path: Path): boolean;
     setSchemaErrorsForPath(path: Path, errors: ValidationError[]): void;
     setAllSchemaErrors(errors: readonly ValidationError[]): void;
     clearSchemaErrors(path?: Path): void;
@@ -912,7 +921,6 @@ 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
@@ -945,6 +953,14 @@ 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
@@ -1086,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
@@ -1097,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
@@ -1428,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`
@@ -1543,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.
  *
@@ -1680,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 };