@wow-two-beta/ui-vue 0.0.4 → 0.0.6

package/dist/formsEngine/AppForm.d.ts

@@ -0,0 +1,259 @@
+import { MaybeRefOrGetter, PublicProps, Ref, VNode } from 'vue';
+import { AppError, Result } from '../foundation/results';
+import { ValidationMessageCatalogue } from '../foundation/validators';
+import { StandardSchemaV1 } from './StandardSchema';
+import { SubmitErrorMap } from './SubmitErrors';
+/** Context for the owned submit request. Pass signal to HTTP/mutation transport. */
+export interface AppFormSubmitContext {
+    readonly signal: AbortSignal;
+}
+/** A display-only step gate. Final submission always uses the configured whole-form schema. */
+export interface AppFormValidationOptions<TValues extends object> {
+    /** Selected paths include descendants. Root/cross-field issues always block the gate. */
+    readonly fields?: ReadonlyArray<string>;
+    /** Optional current-step schema; its output is never used as final submission output. */
+    readonly schema?: StandardSchemaV1<TValues, unknown>;
+}
+/** Defines the options every engine adapter accepts. */
+export interface AppFormOptions<TValues extends object, TOutput = TValues> {
+    /** Seeds detached editing containers. Async prefill uses `/query`, then `reset(data)`. */
+    readonly defaultValues: TValues;
+    /** The whole-form validator — any Standard Schema (zod / valibot / arktype). Sync or async. */
+    readonly schema?: StandardSchemaV1<TValues, TOutput>;
+    /** When client validation runs. `'submit'` re-validates touched fields on change after the first attempt. */
+    readonly validateOn?: 'change' | 'blur' | 'submit';
+    /**
+     * Validate once on mount — seeds `isValid` / field errors before any interaction (edit-screen
+     * validity indicators, wizard step-entry gating). Fields stay untouched (`isTouched` false), so
+     * the initial pass populates state without asserting the user has interacted. Default `false`.
+     */
+    readonly validateOnMount?: boolean;
+    /** Performs the submit with valid values — usually a `useAppMutation` / `useOptimisticMutation` `mutateAsync`. */
+    readonly onSubmit: (values: TOutput, context: AppFormSubmitContext) => Promise<Result<unknown>>;
+    /**
+     * What triggers a submit. `'manual'` (default) = only `handleSubmit` / the `<form @submit>` path.
+     * `'change'` = any field change schedules a submit (settings / live-save); `'blur'` = submit when a
+     * field blurs (save-on-blur). Auto-submits route through the SAME internal submit path as
+     * `handleSubmit`, so validation, parsed output, server-error mapping, the verdict, and
+     * the concurrent-submit guard all apply identically. `reset()` / `reset(data)` / prefill never
+     * auto-submit — only user-origin writes do. Named `'manual'` (not `'submit'`) so it never reads as
+     * a `validateOn` value.
+     */
+    readonly submitOn?: 'change' | 'blur' | 'manual';
+    /** Trailing debounce in ms for `submitOn: 'change'`, coalescing a burst into one submit. Default `0`. */
+    readonly submitDebounceMs?: number;
+    /** Imperative submission focus root; native submit events supply their form automatically. */
+    readonly focusRoot?: () => ParentNode | null | undefined;
+    /**
+     * Disables the whole form — ORs into every `form.Field`'s control-disabled flag (on top of any
+     * per-field `isDisabled`) and makes `handleSubmit` / auto-submit inert. For read-only / role-locked
+     * screens or a while-related-data-loads freeze. Read on every access from the latest options
+     * ({@link AppFormOptionsSource}). Default `false`.
+     */
+    readonly isDisabled?: boolean;
+    /**
+     * Maps an expected submit failure to `path → failures`. Default: `fieldIssues` (ProblemDetails, both .NET
+     * shapes), which keeps each failure's rule code for `messages`. A mapper returning plain strings is
+     * still valid — those render as-is.
+     */
+    readonly mapSubmitError?: (error: unknown) => SubmitErrorMap;
+    /** Rewrites a server error path onto a form path; camelCase per segment by default. */
+    readonly mapFieldPath?: (serverPath: string) => string;
+    /** Safe caller-authored fallback for unexpected submit/validation exceptions. Never includes exception text. */
+    readonly fallbackErrorMessage?: string;
+    /**
+     * Overrides the wording of individual rule codes, merged over `defaultValidationMessages`.
+     *
+     * The point is ONE voice per rule: a failure the client caught and the same failure the server caught
+     * render from the same entry, instead of "Name is required" from one side and "'Name' must not be
+     * empty." from the other. Server codes are normalized onto the shared vocabulary on read
+     * (`foundation/http` `fieldIssues`), so both sides reach the same key.
+     *
+     * Applies to server failures always, and to client failures when the schema is a
+     * `foundation/validators` validator — a third-party spec schema's codes are erased by the spec, so its
+     * messages render as the schema authored them. An unknown code falls back to the source's own message,
+     * which is why wiring this can never render a form worse than not wiring it.
+     *
+     * i18n: swap the whole table per locale off `foundation/i18n`'s `LocaleContext`.
+     */
+    readonly messages?: ValidationMessageCatalogue;
+    /**
+     * Display labels per field path, prefixed to a catalogue-rendered message (`rules[].destination` also
+     * matches every row). Omitted, messages render as bare fragments — correct under a labelled control,
+     * which is why this is opt-in rather than required.
+     */
+    readonly labels?: Readonly<Record<string, string>>;
+}
+/**
+ * How `useAppForm` receives its options. React re-read `options` on every render (latest-ref);
+ * Vue's `setup()` runs once, so the reactive source has to be named: pass a getter (or a ref, or a
+ * `reactive()` object) when an option must stay live — a swapped `schema`, a role-driven
+ * `isDisabled`, a `messages` table that follows the locale. A plain object literal is read once,
+ * which is the right default for `defaultValues` + a closure `onSubmit`.
+ */
+export type AppFormOptionsSource<TValues extends object, TOutput = TValues> = MaybeRefOrGetter<AppFormOptions<TValues, TOutput>>;
+/** The per-field API a `<form.Field>` slot receives. Every member is a live getter, so bind to the object. */
+export interface AppFieldApi<TValue> {
+    /**
+     * The field's value. Writable — assigning runs the same path as {@link setValue}, so a control
+     * binds with `v-model="field.value"` and needs no `@update` handler. (React exposed a read-only
+     * `value` plus `setValue`; both spellings are kept, per the port's keep-React's-name rule.)
+     */
+    value: TValue;
+    readonly setValue: (value: TValue) => void;
+    /** Marks the field touched — the Field glue also wires it onto the control's blur. */
+    readonly onBlur: () => void;
+    /** Client + server messages merged (client first); server messages clear on the next change to the field. */
+    readonly errors: ReadonlyArray<string>;
+    readonly isDirty: boolean;
+    readonly isTouched: boolean;
+}
+/**
+ * The reactive form state. Read a member and you are subscribed — `form.state.isSubmitting` in a
+ * template re-renders that template alone when it flips. Every member is a LIVE getter, so
+ * destructuring takes a snapshot; bind to the object (`form.state`), or reach for
+ * {@link AppForm.useFormState} when a `Ref` is what's wanted.
+ */
+export interface AppFormState<TValues> {
+    /** Read view: write through fields/setValue/array/reset; nested mutation bypasses form notifications. */
+    readonly values: TValues;
+    readonly isDirty: boolean;
+    readonly isValid: boolean;
+    readonly isSubmitting: boolean;
+    readonly isValidating: boolean;
+    /** The submit failure whose mapped paths matched no field — feed the form-level `Alert`. */
+    readonly submitError: AppError | null;
+    /**
+     * The last completed submit's verdict as a reactive slice — `true` when validation passed
+     * AND `onSubmit` returned success, `false` on validation/request failure, `null` before
+     * the first completed attempt and after `reset()`. Cancellation resolves false with a typed cancelled failure.
+     * Mirrors `handleSubmit`'s resolved value,
+     * so the imperative return and this slice never disagree (success banners read here).
+     */
+    readonly isSubmitSuccessful: boolean | null;
+}
+/**
+ * Resolves the field value type for a path: top-level keys infer `TValues[name]`;
+ * deeper dot/index paths stay `unknown` — loose string paths are the documented
+ * contract (typed values, untyped paths), deep typed paths are the tanstack
+ * adapter's escape-hatch territory.
+ */
+export type AppFieldValue<TValues, TPath extends string> = TPath extends keyof TValues ? TValues[TPath] : unknown;
+/**
+ * The path a field binds — a key of `TValues`, or any other string (`rules[0].destination`).
+ *
+ * The `(string & {})` half is load-bearing, not decoration. Constrain the type parameter to a
+ * plain `string` and `vue-tsc` widens the literal in `name="title"` to `string` when it resolves
+ * the tag, so {@link AppFieldValue} falls through to `unknown` and EVERY slot payload silently
+ * loses its type — a plain `.ts` call site infers it correctly, which is what makes the
+ * regression invisible without a template test. A constraint that contains literal types
+ * suppresses that widening. It also earns the editor's completion list for the known keys.
+ */
+export type AppFieldPath<TValues> = (keyof TValues & string) | (string & {});
+/** The props `<form.Field>` accepts — the per-mode control flags (R12); the control renders in its default slot. */
+export interface AppFieldProps<TPath extends string = string> {
+    /** The field path — a top-level key or a dot/index path (`rules[0].destination`). */
+    readonly name: TPath;
+    /** The per-mode disabled flag, exposed to the control via `FormControlContext`. */
+    readonly isDisabled?: boolean;
+    /** The per-mode required flag, exposed to the control via `FormControlContext`. */
+    readonly isRequired?: boolean;
+    /** The per-mode read-only flag, exposed to the control via `FormControlContext`. */
+    readonly isReadOnly?: boolean;
+}
+/**
+ * Field wrapper — always provides `FormControlContext` (id / labelId / errorId / isInvalid /
+ * `errors` / isDisabled / isRequired) so the control + chrome auto-wire aria. Label / helper
+ * chrome stays with the presentation `Field` composed inside the slot — it ADOPTS this
+ * provider (same ids, inherited flags) and renders the context `errors` without
+ * `:error="f.errors[0]"` hand-wiring.
+ *
+ * ```vue
+ * <form.Field name="url" v-slot="f">
+ *   <Field label="Destination">
+ *     <UrlInput v-model="f.value" @blur="f.onBlur" />
+ *   </Field>
+ * </form.Field>
+ * ```
+ *
+ * Typed as a constructor so `TPath` is inferred per usage and the slot payload narrows with it —
+ * the same shape `@tanstack/vue-form` types its own `Field` with, and what `vue-tsc` reads a
+ * component's props/slots off.
+ */
+export interface AppFieldComponent<TValues extends object> {
+    new <TPath extends AppFieldPath<TValues>>(props: AppFieldProps<TPath>): {
+        $props: AppFieldProps<TPath> & PublicProps;
+        $slots: {
+            default?: (field: AppFieldApi<AppFieldValue<TValues, TPath>>) => VNode[];
+        };
+    };
+}
+/** Array helpers at a path — `push` / `insert` / `remove` / `swap` / `move` (R8). Indices are assumed in range. */
+export interface AppArrayApi {
+    readonly push: (value: unknown) => void;
+    readonly insert: (index: number, value: unknown) => void;
+    readonly remove: (index: number) => void;
+    readonly swap: (indexA: number, indexB: number) => void;
+    readonly move: (fromIndex: number, toIndex: number) => void;
+}
+/** What `useAppForm` returns — identical across engines; `TEngine` types the escape hatch. */
+export interface AppForm<TValues extends object, TEngine = unknown> {
+    /** Field wrapper — always provides `FormControlContext` (id / labelId / errorId / isInvalid / `errors` /
+     *  isDisabled / isRequired); the presentation `Field` composed inside the slot adopts it, so
+     *  label/helper/error chrome renders from one provider with zero hand-wiring. */
+    readonly Field: AppFieldComponent<TValues>;
+    /**
+     * The reactive form state — the read path. `form.state.isSubmitting` inside a template or a
+     * `computed` subscribes to that member alone; no selector, no render prop, no nesting to read
+     * four fields. Live getters: bind to `form.state`, never destructure it.
+     */
+    readonly state: AppFormState<TValues>;
+    /** The current values — the shorthand for `form.state.values`, and the same subscription (`form.values.style`). */
+    /** Read view: write through fields/setValue/array/reset; nested mutation bypasses form notifications. */
+    readonly values: TValues;
+    /**
+     * A state slice as a `Ref` — for a `watch` source, and for the one case reactivity alone cannot
+     * express: a COMPOSITE selection with a custom `isEqual`. `computed` always compares with
+     * `Object.is`, so `() => ({ a, b })` invalidates every downstream effect on any store commit;
+     * pass `isEqual` (a shallow-equal) and the previous slice is kept, so nothing downstream re-runs.
+     * Plain single-member reads want `form.state` instead — this is the `Subscribe` replacement, not
+     * the everyday read path.
+     */
+    readonly useFormState: <TSlice>(selector: (state: AppFormState<TValues>) => TSlice, isEqual?: (a: TSlice, b: TSlice) => boolean) => Readonly<Ref<TSlice>>;
+    /**
+     * Validates, runs `onSubmit`, applies mapped server errors to fields, leaves the remainder
+     * in `submitError`. Resolves the verdict — `true` iff validation passed AND `onSubmit`
+     * returned success; `false` on validation/request failure or cancellation. Never rejects, so a
+     * `<form @submit="form.handleSubmit">` handler ignores the return while an imperative caller
+     * (a wizard-step gate) branches on it. The reactive mirror is `state.isSubmitSuccessful`.
+     */
+    readonly handleSubmit: (event?: Event) => Promise<boolean>;
+    /** Validates all values or a step/subset without submitting; touches only selected paths. */
+    readonly validate: (options?: AppFormValidationOptions<TValues>) => Promise<boolean>;
+    /** Aborts the owned request and pending autosave; retains edits, records a cancelled failure. */
+    readonly cancelSubmit: () => void;
+    /** Invalidates old-session work and resets to the supplied new-session values or saved baseline. */
+    readonly invalidateSession: (next?: TValues) => void;
+    /**
+     * Writes a value at a path outside a `<form.Field>` slot — cross-field / derived
+     * writes (name → slug) and sibling-group writes. Top-level keys are typed to their value;
+     * deeper dot/index paths accept `unknown` (the typed-values / untyped-paths contract rule,
+     * mirroring {@link AppFieldValue}). Clears that field's server error like an in-field edit
+     * and runs change-time validation under the active `validateOn`.
+     */
+    readonly setValue: <TPath extends AppFieldPath<TValues>>(path: TPath, value: AppFieldValue<TValues, TPath>) => void;
+    /** Array helpers at a path — `push` / `insert` / `remove` / `swap` / `move` (R8). */
+    readonly array: (path: string) => AppArrayApi;
+    /** Restores the current saved baseline, or establishes `next` as the new editing baseline. */
+    readonly reset: (next?: TValues) => void;
+    /** Applies server field errors outside the submit pipeline, replacing the current server-error overlay. */
+    readonly setFieldErrors: (errors: Record<string, ReadonlyArray<string>>) => void;
+    /** Clears the form-level `submitError` (a dismissible error banner's reset) — leaves field errors untouched. */
+    readonly clearSubmitError: () => void;
+    /** ESCAPE HATCH — the native engine form instance. See the 90/10 rule in docs/analysis/forms-engine.md §4. */
+    readonly engine: TEngine;
+}
+/** The module contract every adapter satisfies — enforced by the conformance suite, swapped by import path. */
+export interface FormEngine {
+    useAppForm<TValues extends object, TOutput = TValues>(options: AppFormOptionsSource<TValues, TOutput>): AppForm<TValues>;
+}

package/dist/formsEngine/DeepEqual.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Structural equality over form-value shapes — primitives, plain objects, arrays,
+ * `ExactNumber`, `Date`, and `File` / `Blob` (upload fields). Powers dirty tracking (values vs the
+ * reset baseline), so it only needs to cover what form values hold; exotic types fall
+ * back to `Object.is`. (`foundation/collections` `Equality` is shallow-only, hence the local
+ * deep variant.)
+ */
+export declare function deepEqual(a: unknown, b: unknown): boolean;

package/dist/formsEngine/FocusFirstInvalid.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Focuses the first invalid, focusable control inside `root` and returns it (`null` when
+ * nothing qualifies — the form is valid, or every invalid control is disabled/hidden).
+ *
+ * `handleSubmit(event)` integrates this after a failed manual attempt. Imperative callers can
+ * provide `focusRoot`; a focusable `[data-form-error-summary]` is its fallback. This helper
+ * remains available for custom orchestration.
+ */
+export declare function focusFirstInvalid(root: ParentNode | null | undefined): HTMLElement | null;

package/dist/formsEngine/FormGlue.d.ts

@@ -0,0 +1,54 @@
+import { Ref } from 'vue';
+import { AppFieldApi, AppFieldComponent, AppFormState } from './AppForm';
+/** The per-field read slice an engine hands back — both adapters' internal field states satisfy it. */
+export interface FieldSlice {
+    readonly value: unknown;
+    readonly errors: ReadonlyArray<string>;
+    readonly isDirty: boolean;
+    readonly isTouched: boolean;
+}
+/** The per-field write seam an engine hands in. */
+export interface FieldOps {
+    readonly getState: (path: string) => FieldSlice;
+    readonly setValue: (path: string, value: unknown) => void;
+    readonly blur: (path: string) => void;
+}
+/**
+ * Builds one path's field API — every member a live getter, so a read inside a template /
+ * `computed` subscribes to exactly that field. `value` is writable, which is what makes
+ * `v-model="field.value"` bind a control with no handler.
+ *
+ * EVERY READ GOES THROUGH ONE `computed`, and that is what makes the subscription per-FIELD rather
+ * than per-form. An engine commits by replacing one state object, so a raw getter would wake every
+ * reader in the form on any commit — the "form-wide re-render" the contract exists to avoid. A
+ * `computed` only notifies when its value changes, and `ops.getState` hands back the SAME slice
+ * object while nothing about the field moved (both engines cache per-path identity), so a control
+ * re-renders on its own edits and sits still through everyone else's.
+ *
+ * Adapters memoize this per path: the object identity is then stable across commits, so a slot
+ * payload does not churn.
+ */
+export declare function createFieldApi(path: string, ops: FieldOps): AppFieldApi<unknown>;
+/**
+ * Builds the `form.state` view — live getters, each backed by its OWN `computed`, so a reader of
+ * `state.isSubmitting` wakes when that flag flips and stays asleep through every unrelated commit.
+ * `values` is one computed too: it re-emits when the values object is replaced (any field write),
+ * which is the granularity a whole-values read can have — narrow further with a `computed` of your
+ * own, or with `form.useFormState`.
+ */
+export declare function createFormStateView<TValues extends object>(getFormState: () => AppFormState<TValues>): AppFormState<TValues>;
+/**
+ * Builds `form.useFormState` — a selected slice as a `Ref`. Without `isEqual` it is a plain
+ * `computed`. With one, the previous slice is HELD when the comparison says nothing changed:
+ * `computed` only ever compares with `Object.is`, so a composite selector (`() => ({a, b})`)
+ * would otherwise hand every downstream effect a fresh object on every store commit.
+ */
+export declare function createUseFormState<TValues extends object>(getFormState: () => AppFormState<TValues>): <TSlice>(selector: (state: AppFormState<TValues>) => TSlice, isEqual?: (a: TSlice, b: TSlice) => boolean) => Readonly<Ref<TSlice>>;
+/**
+ * Builds the `form.Field` component from an adapter's per-field accessor.
+ * `getFieldApi(path)` returns a live-getter API object for that path — the adapter memoizes it
+ * per path, so a slot payload keeps its identity across commits. `isFormDisabled` (optional)
+ * reads the whole-form `isDisabled` option per render and ORs it into every field's
+ * control-disabled flag — the lowest-leverage read-only / role-locked path.
+ */
+export declare function createFieldComponent<TValues extends object>(getFieldApi: (path: string) => AppFieldApi<unknown>, isFormDisabled?: () => boolean): AppFieldComponent<TValues>;

package/dist/formsEngine/FormOperations.d.ts

@@ -0,0 +1,11 @@
+import { AppFormValidationOptions } from './AppForm';
+import { ResolveValidationMessage } from '../foundation/validators';
+import { StandardSchemaV1 } from './StandardSchema';
+/** Matches path segments, so selecting row 1 never selects row 10. Root errors always apply. */
+export declare function includesValidationPath(path: string, fields?: ReadonlyArray<string>): boolean;
+/** Runs a display-only gate and filters issues without bypassing whole-form submit parsing. */
+export declare function validateFormScope<TValues extends object>(values: TValues, options: AppFormValidationOptions<TValues>, schema: StandardSchemaV1<TValues, unknown> | undefined, resolver: ResolveValidationMessage, fallback: string): Promise<Record<string, ReadonlyArray<string>>>;
+/** Settles even when a transport ignores abort, while observing its eventual rejection. */
+export declare function untilFormAbort<T>(work: Promise<T>, signal: AbortSignal, cancelled: T): Promise<T>;
+/** Captures event scope synchronously, then focuses rendered failures only for current manual attempts. */
+export declare function submitWithFocus(submit: () => Promise<boolean>, isCurrent: () => boolean, event?: Event, root?: ParentNode | null): Promise<boolean>;

package/dist/formsEngine/FormSnapshot.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Detaches supported mutable editing containers without serializing platform values.
+ * Plain objects, arrays and Date are copied; ExactNumber, File/Blob, Temporal and custom class
+ * instances are opaque immutable leaves and retain identity. Replace those leaves
+ * through a form setter instead of mutating their internals. Editing trees are acyclic.
+ */
+export declare function snapshotFormValues<T>(value: T): T;

package/dist/formsEngine/Paths.d.ts

@@ -0,0 +1,47 @@
+/** A parsed path segment — a property name or an array index. */
+export type PathKey = string | number;
+/** An array mutation at a path — the vocabulary `AppArrayApi` compiles down to. */
+export type ArrayOperation = {
+    readonly kind: 'push';
+    readonly value: unknown;
+} | {
+    readonly kind: 'insert';
+    readonly index: number;
+    readonly value: unknown;
+} | {
+    readonly kind: 'remove';
+    readonly index: number;
+} | {
+    readonly kind: 'swap';
+    readonly indexA: number;
+    readonly indexB: number;
+} | {
+    readonly kind: 'move';
+    readonly fromIndex: number;
+    readonly toIndex: number;
+};
+/** Parses `'rules[0].destination'` into `['rules', 0, 'destination']`. Tolerant of empty segments; never throws. */
+export declare function parsePath(path: string): ReadonlyArray<PathKey>;
+/** Formats parsed segments back into the canonical string form (`['rules', 0] → 'rules[0]'`). */
+export declare function formatPath(segments: ReadonlyArray<PathKey>): string;
+/** Reads the value at a path; `undefined` when any hop is missing or non-object. */
+export declare function getPath(target: unknown, path: string): unknown;
+/**
+ * Checks structural presence of a path — used to decide whether a mapped server
+ * error path "matches a field". Array hops require the index to be in range.
+ */
+export declare function hasPath(target: unknown, path: string): boolean;
+/** Sets the value at a path immutably — clones only the spine, keeps untouched branches by reference. */
+export declare function setPath<T>(target: T, path: string, value: unknown): T;
+/** Applies an array operation to a row array in place (callers pass a fresh copy). Indices are assumed in range. */
+export declare function mutateRows(rows: unknown[], operation: ArrayOperation): void;
+/**
+ * Remaps a single row-scoped path key (`rules[1].destination`) through an array
+ * operation at `arrayPath`. Returns the key unchanged when it does not sit under
+ * a row of that array, or `null` when its row was removed.
+ */
+export declare function remapPathKey(key: string, arrayPath: string, operation: ArrayOperation): string | null;
+/** Remaps every row-scoped key of an error map through an array operation; removed-row entries drop. */
+export declare function remapPathMap(map: Readonly<Record<string, ReadonlyArray<string>>>, arrayPath: string, operation: ArrayOperation): Readonly<Record<string, ReadonlyArray<string>>>;
+/** Remaps every row-scoped member of a touched set through an array operation; removed-row entries drop. */
+export declare function remapPathSet(set: ReadonlySet<string>, arrayPath: string, operation: ArrayOperation): ReadonlySet<string>;

package/dist/formsEngine/SchemaValidation.d.ts

@@ -0,0 +1,39 @@
+import { AppError, Result } from '../foundation/results';
+import { ResolveValidationMessage, ValidationMessageCatalogue } from '../foundation/validators';
+import { StandardSchemaV1 } from './StandardSchema';
+/** Normalizes a spec issue path (`PropertyKey | { key }` segments) to the canonical string form. */
+export declare function issuePathToString(path: StandardSchemaV1.Issue['path']): string;
+/** Folds failure issues into `path → messages`; a success result yields `{}`. */
+export declare function resultToFieldErrors(result: StandardSchemaV1.Result<unknown>): Record<string, ReadonlyArray<string>>;
+/**
+ * Validates `values` against a Standard Schema. Sync schemas resolve synchronously
+ * (no promise tick between a change and its errors); async schemas return a promise —
+ * the engine's `isValidating` covers them.
+ *
+ * `resolveMessage` renders a house validator's issues through the form's message catalogue; it has no
+ * effect on a third-party spec schema, whose codes the spec already erased.
+ */
+/** A schema result retaining parsed output alongside display-ready field errors. */
+export type FormParseResult<TOutput> = Result<TOutput, AppError & {
+    readonly fieldErrors: Record<string, ReadonlyArray<string>>;
+}>;
+/** Normalizes failed parsing to the shared result contract. */
+export declare function formParseFailure(fieldErrors: Record<string, ReadonlyArray<string>>): FormParseResult<never>;
+/** Parses the editing snapshot once, preserving the Standard Schema output protocol. */
+export declare function parseStandardSchema<TValues extends object, TOutput>(schema: StandardSchemaV1<TValues, TOutput>, values: TValues, resolveMessage?: ResolveValidationMessage): FormParseResult<TOutput> | Promise<FormParseResult<TOutput>>;
+/** Validates a schema for display-only callers that do not consume parsed output. */
+export declare function runStandardSchema<TValues extends object, TOutput = TValues>(schema: StandardSchemaV1<TValues, TOutput>, values: TValues, resolveMessage?: ResolveValidationMessage): Record<string, ReadonlyArray<string>> | Promise<Record<string, ReadonlyArray<string>>>;
+/** The options an adapter reads a message resolver from — the `messages` / `labels` cluster alone. */
+interface MessageOptions {
+    readonly messages?: ValidationMessageCatalogue;
+    readonly labels?: Readonly<Record<string, string>>;
+}
+/**
+ * Memoizes the form's message resolver against the identity of its `messages` / `labels` options —
+ * an adapter calls this on every validation run and every submit failure, and `createMessageResolver`
+ * merges a table over the defaults each time it is called. Shared by both in-repo adapters; an
+ * adapter author wanting the catalogue wires this once and passes the result to `runStandardSchema` and
+ * `resolveSubmitFailure`.
+ */
+export declare function createOptionsMessageResolver(getOptions: () => MessageOptions): () => ResolveValidationMessage;
+export {};

package/dist/formsEngine/SubmitErrors.d.ts

@@ -0,0 +1,28 @@
+import { AppError } from '../foundation/results';
+import { FieldIssue, ResolveValidationMessage } from '../foundation/validators';
+/** One mapped failure: a bare message, or the wide form carrying its rule code and operands. */
+export type SubmitFieldEntry = string | FieldIssue;
+/** What a `mapSubmitError` returns — server path → its failures. */
+export type SubmitErrorMap = Record<string, ReadonlyArray<SubmitFieldEntry>>;
+/** Rewrites a server error path onto a form path, camelCasing each property segment. */
+export declare function defaultMapFieldPath(serverPath: string): string;
+/** Converts unexpected delegate throws into a safe failure without rendering exception text. */
+export declare function toSubmitError(_error: unknown, fallbackMessage?: string): AppError;
+/** The outcome of resolving a thrown submit error: per-field server errors + the form-level remainder. */
+export interface SubmitFailureResolution {
+    /** Mapped messages whose form path matched a field — apply as the server-error overlay. */
+    readonly fieldErrors: Record<string, ReadonlyArray<string>>;
+    /** The coerced failure when fields did not fully represent it; `null` when every mapped path landed. */
+    readonly submitError: AppError | null;
+}
+/**
+ * Resolves a thrown submit error: `mapSubmitError` → `mapFieldPath` per entry →
+ * partition by `isKnownField`. Matches become field errors; if nothing matched — or
+ * some messages could not be placed — the coerced error also lands in `submitError`
+ * so no server message silently disappears.
+ *
+ * `resolveMessage` renders each failure through the form's message catalogue
+ * (`createMessageResolver`); omitted, every failure renders the message the server sent. Resolution
+ * runs AFTER the path rewrite, so a catalogue entry sees the form path its label is keyed by.
+ */
+export declare function resolveSubmitFailure(error: AppError, mapSubmitError: (error: unknown) => SubmitErrorMap, mapFieldPath: (serverPath: string) => string, isKnownField: (path: string) => boolean, _fallbackMessage?: string, resolveMessage?: ResolveValidationMessage): SubmitFailureResolution;

package/dist/formsEngine/UseFieldArray.d.ts

@@ -0,0 +1,87 @@
+import { PublicProps, Ref, VNode } from 'vue';
+import { AppArrayApi, AppFieldApi, AppFieldProps, AppFormState } from './AppForm';
+/** The slice of the `AppForm` contract the helper consumes — every engine's `AppForm` satisfies it. */
+export interface FieldArrayForm {
+    /** Field wrapper — rendered per cell at the row's element path (`${path}[${index}].${name}`). */
+    readonly Field: FieldArrayGlueField;
+    /** Array ops at a path — the helper's ops delegate here (never reimplemented). */
+    readonly array: (path: string) => AppArrayApi;
+    /** Selector-subscribed form state — the helper subscribes to the array's length only. */
+    readonly useFormState: <TSlice>(selector: (state: AppFormState<unknown>) => TSlice, isEqual?: (a: TSlice, b: TSlice) => boolean) => Readonly<Ref<TSlice>>;
+}
+/**
+ * The loose (engine-free `AppFieldComponent`) props shape a `form.Field` accepts at a dynamic
+ * path — DERIVED from the contract's own props at `TPath = string`, never a second copy of them.
+ * A hand-written twin drifts silently and the failure lands on the consumer, as
+ * `useFieldArray(form, path)` no longer accepting an `AppForm` at all.
+ */
+export type FieldArrayGlueFieldProps = AppFieldProps<string>;
+/**
+ * `form.Field` seen loosely — a dynamic path, an untyped cell payload. The slot signature is
+ * deliberately `never`-parametered so that an `AppFieldComponent<TValues>` is assignable here for
+ * ANY `TValues`, which is what lets one helper serve both adapters; the row cell's real payload
+ * type is restored below, on {@link FieldArrayFieldProps}.
+ */
+export interface FieldArrayGlueField {
+    new (props: FieldArrayGlueFieldProps): {
+        $props: FieldArrayGlueFieldProps & PublicProps;
+        $slots: {
+            default?: (...args: never[]) => VNode[];
+        };
+    };
+}
+/** One rendered row — a stable `key` for `v-for` (survives reorder) plus its live array index. */
+export interface FieldArrayRow {
+    readonly key: string;
+    readonly index: number;
+}
+/** Props for the typed row-field accessor — binds `${path}[${index}].${name}`, `f.value` typed as `TItem[name]`. */
+export interface FieldArrayFieldProps<TItem extends object, TName extends keyof TItem & string> {
+    /** The row's current array index (from `row.index`). */
+    readonly index: number;
+    /** The element field key — one level deep into `TItem`. */
+    readonly name: TName;
+    readonly isDisabled?: boolean;
+    readonly isRequired?: boolean;
+    readonly isReadOnly?: boolean;
+}
+/** The typed row-field accessor — one level deep (`keyof TItem`), no recursion, no vendor deep-path types. */
+export interface FieldArrayField<TItem extends object> {
+    new <TName extends keyof TItem & string>(props: FieldArrayFieldProps<TItem, TName>): {
+        $props: FieldArrayFieldProps<TItem, TName> & PublicProps;
+        /** `field.value` / `field.setValue` are typed as `TItem[name]` — no cast, and `v-model="f.value"` binds. */
+        $slots: {
+            default?: (field: AppFieldApi<TItem[TName]>) => VNode[];
+        };
+    };
+}
+/** What `useFieldArray` returns — reactive rows + stable keys, a typed row-field accessor, and element-typed ops. */
+export interface FieldArray<TItem extends object> {
+    /** The current rows — `{ key, index }`; render with `:key="row.key"` so a cell keeps identity through reorder. */
+    readonly rows: ReadonlyArray<FieldArrayRow>;
+    /** The current row count. */
+    readonly length: number;
+    /** The typed row-field accessor — `<array.Field :index="row.index" name="destination">`. */
+    readonly Field: FieldArrayField<TItem>;
+    /** Appends a row (typed to the element — a mistyped push is a compile error). Delegates to `form.array`. */
+    readonly push: (value: TItem) => void;
+    /** Inserts a row at `index`. Delegates to `form.array`. */
+    readonly insert: (index: number, value: TItem) => void;
+    /** Removes the row at `index`. Delegates to `form.array`. */
+    readonly remove: (index: number) => void;
+    /** Swaps two rows. Delegates to `form.array`. */
+    readonly swap: (indexA: number, indexB: number) => void;
+    /** Moves a row. Delegates to `form.array`. */
+    readonly move: (fromIndex: number, toIndex: number) => void;
+}
+/**
+ * Row-render helper for the array at `path`. `TItem` is the row element type; row fields bind
+ * one level deep (`keyof TItem`), typed, cast-free. Reuses `form.array(path)` for the ops
+ * (row + error/touched reindexing stays in the adapter) and subscribes to the array LENGTH
+ * only, so a row container re-renders on structural changes but not on per-row field edits —
+ * each `array.Field` owns its own value subscription. Works identically on `house` + `tanstack`.
+ *
+ * `rows` / `length` are live getters, so `v-for="row in array.rows"` reads the current rows on
+ * every render; destructuring the returned object takes a snapshot of both.
+ */
+export declare function useFieldArray<TItem extends object>(form: FieldArrayForm, path: string): FieldArray<TItem>;

package/dist/formsEngine/adapters/house/HouseFormCore.d.ts

@@ -0,0 +1,34 @@
+import { ShallowRef } from 'vue';
+import { AppFormOptions, AppFormState, AppFormValidationOptions } from '../../AppForm';
+import { ArrayOperation } from '../../Paths';
+/** The per-field slice the `Field` glue reads — identity-stable while its members are unchanged. */
+export interface HouseFieldState {
+    readonly value: unknown;
+    readonly errors: ReadonlyArray<string>;
+    readonly isDirty: boolean;
+    readonly isTouched: boolean;
+}
+/** The native house form instance — what `form.engine` exposes on the house adapter. */
+export interface HouseFormEngine<TValues extends object> {
+    /**
+     * The raw store. Reading `state.value` inside a `computed` / render / `watchEffect` subscribes
+     * to it — the engine's one reactive seam.
+     */
+    readonly state: Readonly<ShallowRef<unknown>>;
+    readonly getFormState: () => AppFormState<TValues>;
+    readonly getFieldState: (path: string) => HouseFieldState;
+    readonly setValue: (path: string, value: unknown) => void;
+    readonly blurField: (path: string) => void;
+    readonly applyArrayOperation: (path: string, operation: ArrayOperation) => void;
+    readonly reset: (next?: TValues) => void;
+    readonly setFieldErrors: (errors: Record<string, ReadonlyArray<string>>) => void;
+    readonly clearSubmitError: () => void;
+    readonly submit: () => Promise<boolean>;
+    /** Validates without submitting — populates errors, marks touched, resolves client validity. */
+    readonly validate: (options?: AppFormValidationOptions<TValues>) => Promise<boolean>;
+    readonly cancelSubmit: () => void;
+    /** Releases the pending auto-submit timer (`submitOn: 'change'`) on scope teardown. */
+    readonly dispose: () => void;
+}
+/** Creates the house form store. `getOptions` reads the latest options (`AppFormOptionsSource`). */
+export declare function createHouseFormEngine<TValues extends object, TOutput = TValues>(getOptions: () => AppFormOptions<TValues, TOutput>): HouseFormEngine<TValues>;

package/dist/formsEngine/adapters/house/UseAppForm.d.ts

@@ -0,0 +1,16 @@
+import { AppForm, AppFormOptionsSource } from '../../AppForm';
+import { HouseFormEngine } from './HouseFormCore';
+/**
+ * The house adapter's `useAppForm` — the facade contract over the zero-dependency
+ * micro-store. The returned form object is stable for the owning scope's lifetime and every
+ * state member on it is a live getter, so `form.values.title` / `form.state.isSubmitting` read
+ * in a template ARE the subscription; `form.engine` exposes the native {@link HouseFormEngine}
+ * (the 90/10 escape hatch — typed here, `unknown` on the shared contract).
+ *
+ * Pass a getter / ref when an option must stay live (see `AppFormOptionsSource`); a plain object
+ * is read once, which is what `defaultValues` + a closure `onSubmit` want.
+ *
+ * Call it in `setup()`: the pending `submitOn: 'change'` timer is released on scope teardown,
+ * which is the whole of React's unmount effect here.
+ */
+export declare function useAppForm<TValues extends object, TOutput = TValues>(options: AppFormOptionsSource<TValues, TOutput>): AppForm<TValues, HouseFormEngine<TValues>>;