attaform 0.31.0 → 0.31.2

package/dist/shared/{attaform.DAo0QBmS.d.mts → attaform.CibLYe9-.d.mts}

@@ -1,160 +1,6 @@
-import { G as GenericForm, F as FormKey, a as UseFormReturnType, _ as RegisterValue, v as Path, w as PathKey, aq as DisplayCtx, ar as GetDisplayState, as as DisplayMachine, at as FieldRecord, au as ErrorCell, ac as ValidationError, av as OriginalsRecord, A as AbstractSchema, ag as WriteMeta, d as DeepPartial, ah as WriteShape, aw as AttaformDomBinding, ax as TransformAbortHolder } from './attaform.DZnrDrNb.mjs';
+import { v as Path, w as PathKey, aq as DisplayCtx, ar as GetDisplayState, as as DisplayMachine, G as GenericForm, F as FormKey, at as FieldRecord, au as ErrorCell, ac as ValidationError, av as OriginalsRecord, A as AbstractSchema, ag as WriteMeta, d as DeepPartial, ah as WriteShape, aw as StructureSnapshot, ax as IndexRemap, ay as AttaformDomBinding, az as TransformAbortHolder, a as UseFormReturnType, _ as RegisterValue } from './attaform.bI_4nKZp.mjs';
 import { Ref, ComputedRef, ShallowRef, App, InjectionKey, Plugin } from 'vue';
 
-/** Options accepted by `injectForm` in place of a bare key string. */
-type InjectFormInput = {
-    readonly key?: FormKey;
-    /**
-     * Set by the Vite transform when this `injectForm` call site sits in
-     * a component whose template / script reads the form's reactive
-     * state. On the server, this enqueues the form for SSR prefetch and
-     * wires `onServerPrefetch` so the descendant awaits the activation
-     * promise before its render emits HTML.
-     *
-     * @internal Transform-emitted. Manual use is the documented escape
-     * hatch when the transform can't reach the reference (dynamic
-     * property access, untransformed bundlers).
-     */
-    readonly __ssrAccessed?: boolean;
-};
-/**
- * Reach an existing form from a descendant component without threading
- * it through props. The counterpart to `useForm`: `useForm` creates and
- * provides, `injectForm` looks up.
- *
- * ```ts
- * // The nearest ancestor's anonymous useForm() call.
- * const form = injectForm<SignupShape>()
- *
- * // A specific form by key, from anywhere in the app.
- * const cart = injectForm<CartShape>('cart')
- * ```
- *
- * A keyed call is a registry lookup, so it is independent of
- * component-tree position. A no-key call takes the closest ambient
- * ancestor and inherits its `formInstanceId`; only an anonymous
- * `useForm()` fills that ambient slot, so a keyed form is reachable
- * only by its key.
- *
- * Returns `null` when nothing matches, so narrow before use:
- *
- * ```ts
- * const form = injectForm<Shape>('signup')
- * if (!form) return
- * form.register('email')
- * ```
- *
- * A keyed miss warns in dev with the registered keys and the call site.
- * Pass the `Form` generic explicitly, since Vue's provide/inject erases
- * generics. The form stays alive for this component's lifetime and is
- * cleaned up once every consumer has unmounted.
- *
- * Components whose nearest `useForm`-calling ancestor is the same one get
- * the same form object for the same form: `injectForm('cart')` in two of
- * its descendants returns one form, with one set of field caches.
- */
-declare function injectForm<Form extends GenericForm, GetValueFormType extends GenericForm = Form>(input?: FormKey | InjectFormInput): UseFormReturnType<Form, GetValueFormType> | null;
-
-/**
- * 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> & {
-    /**
-     * Whether a parent has actually bound this wrapper. `false` until a
-     * `RegisterValue` lands, `true` once one has, and reactive in both
-     * directions: a parent that binds on a later render flips it, and
-     * so does one that stops binding.
-     *
-     * This is the test a dual-mode wrapper reaches for, and the reason
-     * it exists as a field rather than a truthiness check on the
-     * return: the composable cannot answer "is this bound" at setup
-     * time. A parent is free to bind on a later render
-     * (`v-register="ready ? form.register('x') : undefined"`), and
-     * `useRegister` has to keep serving that, so it can never return a
-     * plain `undefined` for "unbound right now". Script-setup code
-     * reading `rv` directly sees the hybrid Proxy, which is an object
-     * and therefore always truthy; a template sees the unwrapped ref,
-     * which IS `undefined` when unbound. `rv?.isBound` reads the same
-     * on both sides (#620).
-     */
-    readonly isBound: boolean;
-};
-/**
- * Options for `useRegister`.
- */
-type UseRegisterOptions = {
-    /**
-     * Declares that this wrapper is used both with and without a form, so
-     * a render with no parent binding is intended rather than a mistake.
-     * Silences the unbound diagnostic; nothing else changes.
-     *
-     * The diagnostic exists because a single-mode wrapper whose parent
-     * forgot `v-register` renders a field that looks fine and stores
-     * nothing, which is an expensive afternoon. Once a wrapper is
-     * deliberately dual-mode, the same signal fires on correct code and
-     * tells the author to do something wrong, so this is the one fact
-     * that separates the two cases and only the author has it (#620).
-     *
-     * Pair it with `rv?.isBound` to branch on what actually happened.
-     */
-    readonly optional?: boolean;
-};
-/**
- * Re-bind a parent's `v-register` onto an inner native element. Use it
- * inside a component that wraps a single form field whose root is NOT
- * the input itself, such as 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()
- * </script>
- *
- * <template>
- *   <label class="field">
- *     <span>Email</span>
- *     <input v-register="rv" />
- *   </label>
- * </template>
- * ```
- *
- * The return is a hybrid: `v-register="rv"` hands the directive the
- * parent's own `RegisterValue`, and `rv.path` / `rv.segments` /
- * `rv.formKey` / `rv.innerRef` read directly in script setup with no
- * `.value` unwrap. Reads inside a `computed` or `watchEffect` re-run
- * when the parent rebinds to a different path.
- *
- * Modifiers on the parent's binding apply at the inner control, so
- * `<MyInput v-register.trim="form.register('email')" />` trims there,
- * together with any the wrapper writes on its own `v-register`.
- *
- * When no parent bound, every field reads `undefined`, so reach for
- * `rv?.path`. `v-register="rv"` is still safe. A wrapper that is meant
- * to render both with and without a form declares it with
- * `useRegister({ optional: true })` and branches on `rv?.isBound`.
- *
- * When the wrapper's root IS the input, Vue's attribute fallthrough
- * already binds it and `useRegister` is unnecessary. For a wrapper
- * that binds several fields, use `injectForm<Form>(key?)` and call
- * `ctx.register(...)` directly.
- */
-declare function useRegister<V = unknown>(options?: UseRegisterOptions): UseRegisterReturn<V> | undefined;
-
 type DynamicPathSweep = {
     /**
      * Note that a cache has just stored an entry for `segments` under
@@ -286,6 +132,13 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
     readonly pathSweep: DynamicPathSweep;
     readonly formKey: FormKey;
     readonly form: Ref<F>;
+    /**
+     * Per-path field records: one per leaf from construction, and one per
+     * container, the root (`[]`) included, once a directive binds to it or a
+     * write takes leaves away beneath it. A container's own record holds the
+     * stamp of that write and the interaction history of the descendants it
+     * took; see `stampContainers` and `foldInteractionHistory`.
+     */
     readonly fields: Map<PathKey, FieldRecord>;
     /**
      * The tagged error store: one cell per error-bearing path, each segregating
@@ -610,6 +463,13 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
      */
     setValueAtPath(path: Path, value: unknown, meta?: WriteMeta): boolean;
     getValueAtPath(path: Path): unknown;
+    /**
+     * The value `path` started as, for a container's `original`: the baseline
+     * at `path`, each array index followed to the slot its element held there.
+     * `undefined` for an element added since and for a path the baseline lacks.
+     * Frozen, since every read shares it.
+     */
+    getOriginalAtPath(path: Path): unknown;
     /**
      * Stable identity for the array element at `path`, the token the array
      * engine maintains across structural mutations. Empty for anything that is
@@ -641,6 +501,31 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
      * empty is skipped.
      */
     restoreErrorCells(entries: ReadonlyArray<readonly [PathKey, ErrorCell]>): void;
+    /**
+     * The per-element bookkeeping as it stands, for a history position to put
+     * back with its value (see `StructureSnapshot`). The entries are copied,
+     * and the records they hold are never mutated in place, so the snapshot
+     * stays detached from the live store.
+     */
+    captureStructure(): StructureSnapshot;
+    /**
+     * Put a `captureStructure()` back, before the value it was taken with is
+     * restored, so the write that restores it compares each row against its
+     * own baseline. Every reading it can change is woken.
+     *
+     * The field records follow their rows: each of `remaps` moves the records
+     * under its array's elements, in order, handing a removed element's
+     * history to the array and its ancestors, and each of `returning`, a
+     * record of a row the restore brings back, takes its place at its path,
+     * its element not yet on the page.
+     */
+    restoreStructure(snapshot: StructureSnapshot, remaps: ReadonlyArray<readonly [Path, IndexRemap]>, returning: readonly FieldRecord[]): void;
+    /**
+     * Hears the records a removal releases while a history module is attached,
+     * so an undo can bring a row back with its interaction history. Set by the
+     * module, so a form without one never carries it.
+     */
+    noteReleased?: ((records: readonly FieldRecord[]) => void) | undefined;
     /**
      * Merged read of the cell at `path`, in schema -> blank -> user order:
      * structural validation first, the synthesized blank entry between, user
@@ -695,18 +580,19 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
      */
     markInteracted(path: Path): void;
     /**
-     * Walk every active-variant leaf under `segments` and flip `touched: true`.
-     * Powers `form.touch(path?)`. Idempotent, and touches neither value nor
-     * `focused` / `blurred`, nor does it trigger validation.
+     * Walk every active-variant leaf under `segments`, and every container there
+     * holding no leaf, and flip `touched: true`. Powers `form.touch(path?)`.
+     * Idempotent, and touches neither value nor `focused` / `blurred`, nor does
+     * it trigger validation.
      */
     touchAtPath(segments: Path): void;
     /**
-     * Walk every active-variant leaf under `segments` and flip the whole
-     * interaction ladder (`touched` / `interacted` / `blurredAfterInteraction`),
-     * as though the user had focused, edited and left each one. Powers
-     * `form.interact(path?)`. Idempotent, and leaves value / `focused` /
-     * `blurred` alone. Returns whether any leaf resolved, so the caller can skip
-     * validation and dev-warn on an empty path.
+     * Walk every active-variant leaf under `segments`, and every container there
+     * holding no leaf, and flip the whole interaction ladder (`touched` /
+     * `interacted` / `blurredAfterInteraction`), as though the user had focused,
+     * edited and left each one. Powers `form.interact(path?)`. Idempotent, and
+     * leaves value / `focused` / `blurred` alone. Returns whether anything
+     * resolved, so the caller can skip validation on an unresolved path.
      */
     interactAtPath(segments: Path): boolean;
     /**
@@ -729,18 +615,19 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
      * insert or removal) against 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 cannot
-     * see the shape change.
+     * see the shape change. `key` is the canonical key of `path`.
      */
-    hasStructuralChangeUnder(path: Path): boolean;
+    hasStructuralChangeUnder(path: Path, key: PathKey): boolean;
     /**
-     * Whether a baseline-present container under `path` was replaced wholesale
-     * by a non-container (`setValue('profile', undefined)` and the like) and is
-     * still absent. The other half of removal-driven `dirty`: every leaf in such
-     * a subtree vanishes at once, so neither the present-leaf walk nor the array
-     * tracker sees the loss. Self-filters by current liveness, so a refilled
-     * path stops counting.
+     * Whether a path under `path` that held a real baseline value was removed
+     * and is still absent: a dropped key, an emptied container, a row a
+     * wholesale write took away. The other half of removal-driven `dirty`: the
+     * present-leaf walk never visits an absent leaf, and the array tracker
+     * follows only array lengths and orders. A path a later write brought back
+     * stops counting, and the present-leaf walk judges it instead. `key` is the
+     * canonical key of `path`.
      */
-    hasRemovedSubtreeUnder(path: Path): boolean;
+    hasRemovedSubtreeUnder(path: Path, key: PathKey): boolean;
     getFieldRecord(path: Path): FieldRecord | undefined;
     /**
      * Cancel every in-flight field-level validation run: clear the timers of
@@ -849,6 +736,160 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
     dispose(): void;
 };
 
+/** Options accepted by `injectForm` in place of a bare key string. */
+type InjectFormInput = {
+    readonly key?: FormKey;
+    /**
+     * Set by the Vite transform when this `injectForm` call site sits in
+     * a component whose template / script reads the form's reactive
+     * state. On the server, this enqueues the form for SSR prefetch and
+     * wires `onServerPrefetch` so the descendant awaits the activation
+     * promise before its render emits HTML.
+     *
+     * @internal Transform-emitted. Manual use is the documented escape
+     * hatch when the transform can't reach the reference (dynamic
+     * property access, untransformed bundlers).
+     */
+    readonly __ssrAccessed?: boolean;
+};
+/**
+ * Reach an existing form from a descendant component without threading
+ * it through props. The counterpart to `useForm`: `useForm` creates and
+ * provides, `injectForm` looks up.
+ *
+ * ```ts
+ * // The nearest ancestor's anonymous useForm() call.
+ * const form = injectForm<SignupShape>()
+ *
+ * // A specific form by key, from anywhere in the app.
+ * const cart = injectForm<CartShape>('cart')
+ * ```
+ *
+ * A keyed call is a registry lookup, so it is independent of
+ * component-tree position. A no-key call takes the closest ambient
+ * ancestor and inherits its `formInstanceId`; only an anonymous
+ * `useForm()` fills that ambient slot, so a keyed form is reachable
+ * only by its key.
+ *
+ * Returns `null` when nothing matches, so narrow before use:
+ *
+ * ```ts
+ * const form = injectForm<Shape>('signup')
+ * if (!form) return
+ * form.register('email')
+ * ```
+ *
+ * A keyed miss warns in dev with the registered keys and the call site.
+ * Pass the `Form` generic explicitly, since Vue's provide/inject erases
+ * generics. The form stays alive for this component's lifetime and is
+ * cleaned up once every consumer has unmounted.
+ *
+ * Components whose nearest `useForm`-calling ancestor is the same one get
+ * the same form object for the same form: `injectForm('cart')` in two of
+ * its descendants returns one form, with one set of field caches.
+ */
+declare function injectForm<Form extends GenericForm, GetValueFormType extends GenericForm = Form>(input?: FormKey | InjectFormInput): UseFormReturnType<Form, GetValueFormType> | null;
+
+/**
+ * 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> & {
+    /**
+     * Whether a parent has actually bound this wrapper. `false` until a
+     * `RegisterValue` lands, `true` once one has, and reactive in both
+     * directions: a parent that binds on a later render flips it, and
+     * so does one that stops binding.
+     *
+     * This is the test a dual-mode wrapper reaches for, and the reason
+     * it exists as a field rather than a truthiness check on the
+     * return: the composable cannot answer "is this bound" at setup
+     * time. A parent is free to bind on a later render
+     * (`v-register="ready ? form.register('x') : undefined"`), and
+     * `useRegister` has to keep serving that, so it can never return a
+     * plain `undefined` for "unbound right now". Script-setup code
+     * reading `rv` directly sees the hybrid Proxy, which is an object
+     * and therefore always truthy; a template sees the unwrapped ref,
+     * which IS `undefined` when unbound. `rv?.isBound` reads the same
+     * on both sides (#620).
+     */
+    readonly isBound: boolean;
+};
+/**
+ * Options for `useRegister`.
+ */
+type UseRegisterOptions = {
+    /**
+     * Declares that this wrapper is used both with and without a form, so
+     * a render with no parent binding is intended rather than a mistake.
+     * Silences the unbound diagnostic; nothing else changes.
+     *
+     * The diagnostic exists because a single-mode wrapper whose parent
+     * forgot `v-register` renders a field that looks fine and stores
+     * nothing, which is an expensive afternoon. Once a wrapper is
+     * deliberately dual-mode, the same signal fires on correct code and
+     * tells the author to do something wrong, so this is the one fact
+     * that separates the two cases and only the author has it (#620).
+     *
+     * Pair it with `rv?.isBound` to branch on what actually happened.
+     */
+    readonly optional?: boolean;
+};
+/**
+ * Re-bind a parent's `v-register` onto an inner native element. Use it
+ * inside a component that wraps a single form field whose root is NOT
+ * the input itself, such as 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()
+ * </script>
+ *
+ * <template>
+ *   <label class="field">
+ *     <span>Email</span>
+ *     <input v-register="rv" />
+ *   </label>
+ * </template>
+ * ```
+ *
+ * The return is a hybrid: `v-register="rv"` hands the directive the
+ * parent's own `RegisterValue`, and `rv.path` / `rv.segments` /
+ * `rv.formKey` / `rv.innerRef` read directly in script setup with no
+ * `.value` unwrap. Reads inside a `computed` or `watchEffect` re-run
+ * when the parent rebinds to a different path.
+ *
+ * Modifiers on the parent's binding apply at the inner control, so
+ * `<MyInput v-register.trim="form.register('email')" />` trims there,
+ * together with any the wrapper writes on its own `v-register`.
+ *
+ * When no parent bound, every field reads `undefined`, so reach for
+ * `rv?.path`. `v-register="rv"` is still safe. A wrapper that is meant
+ * to render both with and without a form declares it with
+ * `useRegister({ optional: true })` and branches on `rv?.isBound`.
+ *
+ * When the wrapper's root IS the input, Vue's attribute fallthrough
+ * already binds it and `useRegister` is unnecessary. For a wrapper
+ * that binds several fields, use `injectForm<Form>(key?)` and call
+ * `ctx.register(...)` directly.
+ */
+declare function useRegister<V = unknown>(options?: UseRegisterOptions): UseRegisterReturn<V> | undefined;
+
 /**
  * Public types for `useWizard`, the multistep-form orchestrator.
  *