attaform 0.30.1 → 0.31.0

package/dist/shared/{attaform.Br8EBn5B.d.mts → attaform.DZnrDrNb.d.mts}

@@ -888,8 +888,6 @@ type SchemaParseErrorWithData<TData> = {
 };
 /** Settled schema-level verdict. Discriminate on `success`. */
 type SchemaParseResult<TData> = SchemaParseSuccess<TData> | SchemaParseErrorWithData<TData> | SchemaParseErrorWithoutData;
-/** Schema-level `getDefaultValues` verdict: defaults always come back. */
-type SchemaDefaultsResult<TData> = SchemaParseSuccess<TData> | SchemaParseErrorWithData<TData>;
 /** Settled validation result when the form or subtree parsed successfully. */
 type ValidationResponseSuccess<TData> = SchemaParseSuccess<TData> & {
     /** The form this verdict belongs to. Stamped by the store, not the schema. */
@@ -977,7 +975,31 @@ type GetDefaultValuesConfig<Form> = {
  * library.
  */
 type AbstractSchema<Form, GetValueFormType> = {
-    getDefaultValues(config: GetDefaultValuesConfig<Form>): SchemaDefaultsResult<Form>;
+    /**
+     * The form's starting value: the schema's defaults, with
+     * `config.constraints` merged over them and any shape the merge broke
+     * repaired. Derivation only. Nothing is validated here, so no
+     * refinement, check or transform runs; `validateSync` is the verdict.
+     */
+    getDefaultValues(config: GetDefaultValuesConfig<Form>): Form;
+    /**
+     * The schema's synchronous verdict on `data` as a whole form, as a
+     * list of failures: empty when the data passes.
+     *
+     * The runtime seeds the schema error channel with it whenever it
+     * establishes a baseline: on the starting value, the first time
+     * anything reads or writes the form's errors, and on `reset()`. A form
+     * starting from invalid defaults therefore reads invalid from its
+     * first render.
+     * A hydrating client never calls it, since the server's verdict
+     * arrives with the payload.
+     *
+     * Adapters MUST NOT throw: a refinement that throws, or a schema whose
+     * verdict resolves only through a Promise, returns `[]` and leaves the
+     * verdict to the async pass that `needsAsyncValidation` queues. An
+     * adapter with no synchronous parse returns `[]` unconditionally.
+     */
+    validateSync(data: unknown): ValidationError[];
     /**
      * The schema-prescribed default at `path`. The runtime uses it to
      * fill structural gaps, so every `setValue` write leaves the form
@@ -1325,8 +1347,8 @@ type AbstractSchema<Form, GetValueFormType> = {
     /**
      * Whether `validateAtPath` MAY have to run asynchronously to surface
      * every error this schema can produce. The runtime asks at
-     * construction: `false` means the construction-time sync seed is
-     * authoritative and no extra microtask is spent, `true` queues a
+     * construction: `false` means the synchronous verdict on the starting
+     * value is authoritative and no extra microtask is spent, `true` queues a
      * one-shot full-form async pass so async-only verdicts (refinements,
      * transforms or pipes that resolve only through a Promise) surface
      * without waiting for a user mutation.
@@ -1338,7 +1360,10 @@ type AbstractSchema<Form, GetValueFormType> = {
      * For a per-path query, compose with `getSchemasAtPath(path)`: each
      * candidate sub-schema exposes its own `needsAsyncValidation`, so
      * "does the cargo subtree contain async work?" is the union of the
-     * per-candidate answers, with no separate top-level overload.
+     * per-candidate answers, with no separate top-level overload. A root
+     * that answers `false` answers for every path, and the runtime then
+     * asks no sub-schema, so never answer `false` at the root of a tree
+     * where a sub-schema would answer `true`.
      */
     needsAsyncValidation?(): boolean;
     /**
@@ -1378,6 +1403,20 @@ type AbstractSchema<Form, GetValueFormType> = {
      * that disables variant reshape and stub correction for the form.
      */
     hasDiscriminatedUnions?(): boolean;
+    /**
+     * Whether `isPreprocessOrCoerceLeaf` can answer `true` at any path:
+     * the schema holds a preprocess-style normalizer or a coerce
+     * primitive somewhere. The store reads it once at construction.
+     * `false` lets it skip recording which paths the consumer authored,
+     * a set that is only read at such leaves.
+     *
+     * Optional, and an adapter that omits it is treated as holding one,
+     * which keeps that bookkeeping on. Never return `false` for a schema
+     * where `isPreprocessOrCoerceLeaf` answers `true` anywhere: verdicts
+     * at a path the consumer authored with `undefined` would then stay
+     * hidden.
+     */
+    hasPreprocessOrCoerce?(): boolean;
 };
 /**
  * A discriminated union as the adapter reports it: the discriminator
@@ -1583,7 +1622,7 @@ type WriteMeta = {
 type HistoryKernel = {
     readonly form: Ref<unknown>;
     readonly blankPaths: Set<PathKey>;
-    readonly errorCells: Map<PathKey, ErrorCell>;
+    readonly errorCells: () => Map<PathKey, ErrorCell>;
     onFormChange(listener: (next: unknown, meta?: WriteMeta) => void): () => void;
     applyFormReplacement(next: unknown): void;
     restoreErrorCells(entries: ReadonlyArray<readonly [PathKey, ErrorCell]>): void;
@@ -2184,6 +2223,32 @@ type AttaformDomBinding = {
         path: Path;
         element: HTMLElement;
     } | null;
+    readonly hostChannel: HostChannel;
+};
+/**
+ * The write policy for a `v-register` component host, held on the DOM
+ * binding so it stays in the directive cluster's lazy graph. Applies the
+ * binding site's modifiers, runs register `transforms` and schema
+ * coercion, and buffers `.lazy` writes while focus is inside the host.
+ *
+ *   - `write` commits a value the host emitted through
+ *     `update:modelValue`.
+ *   - `writeInput` takes an `input` emit and commits it only when the
+ *     payload carries the live value as an own `value` property.
+ *   - `markEditing` records focus entering or leaving the host. Leaving
+ *     commits a buffered `.lazy` value, or the trimmed form under `.trim`.
+ *   - `holdsDraft` reports a buffered `.lazy` value that storage has not
+ *     moved past, the edit a re-render must leave on screen.
+ *   - `release` drops any buffered value when the host unmounts.
+ *
+ * @internal
+ */
+type HostChannel = {
+    readonly write: (rv: RegisterValue, value: unknown, modifiers: HostModifiers) => boolean;
+    readonly writeInput: (rv: RegisterValue, payload: unknown, modifiers: HostModifiers) => boolean;
+    readonly markEditing: (rv: RegisterValue, editing: boolean, modifiers: HostModifiers) => void;
+    readonly holdsDraft: (rv: RegisterValue) => boolean;
+    readonly release: (rv: RegisterValue) => void;
 };
 /**
  * Factory the directive and `useRegister` inject through
@@ -2244,16 +2309,39 @@ type RegisterValue<Value = unknown> = Readonly<{
     setValueWithInternalPath: (value: unknown, meta?: WriteMeta) => boolean;
     /**
      * Commit a value emitted by a third-party component bound through
-     * `v-register`'s compile-time v-model desugar. Writes the component's
-     * typed model output as authoritative, with no coercion, AND marks
-     * the field interacted, since a v-model host has no DOM input
-     * listener to flip the sticky `interacted` bit. The injected
-     * `onUpdate:modelValue` handler is the only caller. `true` when the
-     * write was accepted.
+     * `v-register`'s compile-time v-model desugar, and mark the field
+     * interacted, since a v-model host has no DOM input listener to flip
+     * the sticky `interacted` bit. The write takes the same path a native
+     * input's does: the binding site's `.number` / `.trim` / `.lazy`
+     * modifiers, then register `transforms`, then schema coercion. The
+     * injected `onUpdate:modelValue` handler is the caller, passing the
+     * modifiers as a static literal. `true` when the write was accepted
+     * or buffered.
      *
      * @internal
      */
-    setValueFromHost: (value: unknown) => boolean;
+    setValueFromHost: (value: unknown, modifiers: HostModifiers) => boolean;
+    /**
+     * Commit the live value from a component host's `input` emit. A
+     * payload that is a non-Event object owning a `value` property (the
+     * shape PrimeVue's InputNumber reports per keystroke) writes that
+     * value through `setValueFromHost`; anything else, a native `Event`
+     * reaching a fallthrough listener included, is ignored and returns
+     * `false`. The injected `onInput` handler is the only caller.
+     *
+     * @internal
+     */
+    setValueFromHostInput: (payload: unknown, modifiers: HostModifiers) => boolean;
+    /**
+     * The final step of a component-host write, after modifiers,
+     * transforms and coercion: an empty signal (`''`, `null` or
+     * `undefined`) the field's schema does not admit marks the field
+     * blank, and anything else writes through. Called by the host write
+     * channel.
+     *
+     * @internal
+     */
+    commitFromHost: (value: unknown) => boolean;
     /**
      * Mark this field DOM-connected during SSR, so a server-rendered
      * template reading `form.fields.<path>.connected` does not flicker on
@@ -2312,11 +2400,12 @@ type RegisterValue<Value = unknown> = Readonly<{
      * every later registration.
      *
      * Optional, so a hand-rolled RegisterValue owning its own element
-     * handling need not declare it.
+     * handling need not declare it. Returns the armed binding, which is how
+     * the directive reaches the host write channel.
      *
      * @internal
      */
-    ensureDomBinding?: (factory: DomBindingFactory) => void;
+    ensureDomBinding?: (factory: DomBindingFactory) => AttaformDomBinding;
     /**
      * Canonical JSON-encoded path key for this binding, such as
      * `'["items",0,"name"]'`. Useful for stable Map and Set keys, log
@@ -2576,9 +2665,10 @@ type CustomRegisterDirective<T, Modifiers extends string = string> = ObjectDirec
     /**
      * Snapshot of the last `value.innerRef.value` reference the
      * directive's DOM-sync (setSelected / setChecked / radio
-     * `el.checked = …`) was applied for. Used by every input
-     * directive's `updated` / `beforeUpdate` to skip the per-render
-     * DOM sync when the model is identity-unchanged, so a parent
+     * `el.checked = …` / text `el.value = …`) was applied for. Used by
+     * every input directive's `updated` / `beforeUpdate` to skip the
+     * per-render DOM sync when the model is identity-unchanged (for
+     * text, a focused `.lazy` edit is held through it), so a parent
      * re-render (a typed character in a sibling, an async-validation
      * tick, any reactive read) cannot clobber an in-progress user
      * interaction. Identity comparison is sound because every form
@@ -2604,16 +2694,18 @@ type CustomRegisterDirective<T, Modifiers extends string = string> = ObjectDirec
 }, RegisterValue | undefined, Modifiers, string>;
 /**
  * Modifier names supported by `v-register` on `<input type="text">`,
- * `<input type="number">`, and `<textarea>`. Mirrors Vue's
- * `v-model` modifier semantics on the same elements; combine freely
- * (`<input v-register.lazy.trim.number="..." />`).
+ * `<input type="number">`, `<textarea>`, and component hosts. Mirrors
+ * Vue's `v-model` modifier semantics on the same elements; combine
+ * freely (`<input v-register.lazy.trim.number="..." />`).
  */
 type RegisterTextModifier = 
 /**
  * Write on `change` (blur) instead of `input`. The reactive
  * model only updates after the user tabs/clicks out of the
  * field. IME composition handlers are skipped under `.lazy`, since
- * composition events do not gate writes.
+ * composition events do not gate writes. On a component host the
+ * last value emitted while focus is inside the host commits when
+ * focus leaves it.
  */
 'lazy'
 /**
@@ -2621,18 +2713,30 @@ type RegisterTextModifier =
  * the user's raw input (whitespace included) while they're
  * typing; on `change` (blur / commit) the value is trimmed
  * once and written back to both the model and the visible DOM.
- * Combine with `.lazy` to skip the mid-typing writes entirely.
+ * Combine with `.lazy` to skip the mid-typing writes entirely. On a
+ * component host the trimmed value commits when focus leaves the
+ * host.
  */
  | 'trim'
 /**
- * Cast the value with `parseFloat` before writing. A value that
- * does not parse as a number (`'abc'`) passes through unchanged,
- * and the slim-primitive gate then sees a string heading for a
- * numeric slot and rejects the write. Auto-applied for
- * `<input type="number">`, where an explicit `.number` is
- * redundant.
+ * Cast the value with `parseFloat` before writing. An empty field,
+ * or text that does not parse as a number (`'abc'`), marks the field
+ * blank instead of writing a string. On a component host the cast
+ * applies to string emits, and a value the component already typed
+ * passes through. Auto-applied for `<input type="number">`, where an
+ * explicit `.number` is redundant.
  */
  | 'number';
+/**
+ * The `v-register` modifiers a component host honours, carried from the
+ * binding site to the host write channel as a static literal that the
+ * compile-time bridge transform emits. Shaped like Vue's directive
+ * modifiers, so the directive passes a binding's modifiers to the channel
+ * unchanged.
+ *
+ * @internal
+ */
+type HostModifiers = Readonly<Partial<Record<RegisterTextModifier, boolean>>>;
 /**
  * v-register directive variant for `<input type="text">`,
  * `<input type="number">` and `<textarea>`. Supports the `.lazy`,
@@ -4549,5 +4653,5 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
     blankPaths: ComputedRef<BlankPathsView>;
 };
 
-export { ROOT_PATH as R, canonicalizePath as aj, isPathPrefix as ak, isUnset as al, parseDottedPath as am, unset as an, ROOT_PATH_KEY as z };
-export type { SchemaDefaultsResult as $, AbstractSchema as A, ReactiveValidationStatus as B, CustomDirectiveRegisterAssignerFn as C, DefaultValuesInput as D, ErrorInput as E, FormKey as F, GenericForm as G, HandleSubmit as H, IsTuple as I, JoinSegments as J, KeyofUnion as K, LiftedValueShape as L, MetaTrackerValue as M, NestedReadType as N, OnError as O, ParseOptions as P, RecordPath as Q, RecordValue as S, RegisterDirective as T, UseFormConfiguration as U, RegisterFlatPath as V, RegisterOptions as W, RegisterSelectModifier as X, RegisterTextModifier as Y, RegisterTransform as Z, RegisterValue as _, UseFormReturnType as a, SchemaParseErrorWithData as a0, SchemaParseErrorWithoutData as a1, SchemaParseResult as a2, SchemaParseSuccess as a3, Segment as a4, SetValueCallback as a5, SetValuePayload as a6, SettledValidationStatus as a7, SlimPrimitiveKind as a8, SubmitHandler as a9, Unset as aa, ValidateOn as ab, ValidateOnConfig as ac, ValidationError as ad, ValidationResponse as ae, ValidationResponseWithoutValue as af, ValueOfUnion as ag, WriteMeta as ah, WriteShape as ai, RegisterModelDynamicCustomDirective as ao, SchemaFactoryOptions as ap, AcceptableDefaults as aq, DisplayCtx as ar, GetDisplayState as as, DisplayMachine as at, FieldRecord as au, ErrorCell as av, OriginalsRecord as aw, AttaformDomBinding as ax, TransformAbortHolder as ay, ArrayItem as b, ArrayPath as c, DeepPartial as d, DefaultValuesShape as e, DisplayState as f, ErrorsProxyShape as g, FieldMetaPayload as h, FieldState as i, FieldStateMap as j, FieldStateMapEntry as k, FlatPath as l, FormErrorRecord as m, FormErrorsSurface as n, FormMeta as o, HistoryPlugin as p, IsUnion as q, Json as r, NestedType as s, OnSubmit as t, PartialFlatPath as u, Path as v, PathKey as w, PendingValidationStatus as x, Primitive as y };
+export { ROOT_PATH as R, canonicalizePath as ai, isPathPrefix as aj, isUnset as ak, parseDottedPath as al, unset as am, ROOT_PATH_KEY as z };
+export type { SchemaParseErrorWithData as $, AbstractSchema as A, ReactiveValidationStatus as B, CustomDirectiveRegisterAssignerFn as C, DefaultValuesInput as D, ErrorInput as E, FormKey as F, GenericForm as G, HandleSubmit as H, IsTuple as I, JoinSegments as J, KeyofUnion as K, LiftedValueShape as L, MetaTrackerValue as M, NestedReadType as N, OnError as O, ParseOptions as P, RecordPath as Q, RecordValue as S, RegisterDirective as T, UseFormConfiguration as U, RegisterFlatPath as V, RegisterOptions as W, RegisterSelectModifier as X, RegisterTextModifier as Y, RegisterTransform as Z, RegisterValue as _, UseFormReturnType as a, SchemaParseErrorWithoutData as a0, SchemaParseResult as a1, SchemaParseSuccess as a2, Segment as a3, SetValueCallback as a4, SetValuePayload as a5, SettledValidationStatus as a6, SlimPrimitiveKind as a7, SubmitHandler as a8, Unset as a9, ValidateOn as aa, ValidateOnConfig as ab, ValidationError as ac, ValidationResponse as ad, ValidationResponseWithoutValue as ae, ValueOfUnion as af, WriteMeta as ag, WriteShape as ah, RegisterModelDynamicCustomDirective as an, SchemaFactoryOptions as ao, AcceptableDefaults as ap, DisplayCtx as aq, GetDisplayState as ar, DisplayMachine as as, FieldRecord as at, ErrorCell as au, OriginalsRecord as av, AttaformDomBinding as aw, TransformAbortHolder as ax, ArrayItem as b, ArrayPath as c, DeepPartial as d, DefaultValuesShape as e, DisplayState as f, ErrorsProxyShape as g, FieldMetaPayload as h, FieldState as i, FieldStateMap as j, FieldStateMapEntry as k, FlatPath as l, FormErrorRecord as m, FormErrorsSurface as n, FormMeta as o, HistoryPlugin as p, IsUnion as q, Json as r, NestedType as s, OnSubmit as t, PartialFlatPath as u, Path as v, PathKey as w, PendingValidationStatus as x, Primitive as y };