@wow-two-beta/ui-vue 0.0.2

package/dist/forms-engine/AppForm.d.ts

@@ -0,0 +1,258 @@
+import { MaybeRefOrGetter, PublicProps, Ref, VNode } from 'vue';
+import { ApiError } from '../foundation/http';
+import { ValidationMessageCatalogue } from '../foundation/validation';
+import { StandardSchemaV1 } from './StandardSchema';
+import { SubmitErrorMap } from './SubmitErrors';
+/** Defines the options every engine adapter accepts. */
+export interface AppFormOptions<TValues extends object> {
+    /** The initial values. Async prefill (edit screens) stays on `/query` — render the form once loaded, or `reset(data)`. */
+    readonly defaultValues: TValues;
+    /** The whole-form validator — any Standard Schema (zod / valibot / arktype). Sync or async. */
+    readonly schema?: StandardSchemaV1<TValues>;
+    /** When client validation runs. `'submit'` (default) 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;
+    /**
+     * How a failed client validation gates the submit. `false` (default) blocks `onSubmit` on errors
+     * (the client is the gate); `true` validates (errors still populate + render, advisory) but runs
+     * `onSubmit` regardless — the **backend is the source of truth**. Belongs here, on the
+     * validation-config surface, because it is a validation→submit *gate policy*, not a submit callback.
+     * The verdict (`handleSubmit` / `isSubmitSuccessful`) then reflects `onSubmit`'s outcome, not the
+     * bypassed client gate.
+     */
+    readonly submitInvalid?: boolean;
+    /** Performs the submit with valid values — usually a `useAppMutation` / `useOptimisticMutation` `mutateAsync`. */
+    readonly onSubmit: (values: TValues) => Promise<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, the `submitInvalid` gate, 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';
+    /** Debounce (ms, trailing) for `submitOn: 'change'` — coalesces a change burst into one submit. Default `0`. Ignored for `'blur'` / `'manual'`. */
+    readonly submitDebounceMs?: number;
+    /**
+     * 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 a thrown submit error 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. Default: camelCase per segment (`Rules[0].Destination` → `rules[0].destination`). */
+    readonly mapFieldPath?: (serverPath: string) => string;
+    /**
+     * The message used when a submit failure is neither an `ApiError`, an `Error`, nor a
+     * string (e.g. a thrown plain object) — the last SDK-authored English literal on the
+     * submit path. Override for i18n. Default: `'Unknown error'`.
+     */
+    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/validation` 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> = MaybeRefOrGetter<AppFormOptions<TValues>>;
+/** The per-field API a `<form.Field>` slot receives. Every member is a LIVE getter — destructuring takes a snapshot, 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: readonly 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> {
+    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: ApiError | null;
+    /**
+     * The last completed submit's verdict as a reactive slice — `true` when validation passed
+     * AND `onSubmit` resolved, `false` when validation failed or `onSubmit` threw, `null` before
+     * the first completed attempt and after `reset()`. 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`). */
+    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`
+     * resolved; `false` on validation failure or an `onSubmit` throw. 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 the current values WITHOUT submitting — runs the whole-form schema, populates
+     * `field.errors`, and marks fields touched so the errors display (the "validate now" gate), then
+     * resolves the client validity. `onSubmit` never runs. The clean single-form multi-step gate
+     * (`const ok = await form.validate()` before advancing a wizard step) and the imperative
+     * "is it valid now" check. Never rejects. Mirrors RHF `trigger` / TanStack `validateAllFields`.
+     */
+    readonly validate: () => Promise<boolean>;
+    /**
+     * 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;
+    /** Resets to `defaultValues`, or re-seeds with `next` (edit-mode prefill — kills smart-qr's 13-setter effect). */
+    readonly reset: (next?: TValues) => void;
+    /** Applies server field errors outside the submit pipeline (e.g. a deferred backend check). Replaces the current server-error overlay. */
+    readonly setFieldErrors: (errors: Record<string, 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>(options: AppFormOptionsSource<TValues>): AppForm<TValues>;
+}

package/dist/forms-engine/DeepEqual.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Structural equality over form-value shapes — primitives, plain objects, arrays,
+ * `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/utils` `Equality` is shallow-only, hence the local
+ * deep variant.)
+ */
+export declare function deepEqual(a: unknown, b: unknown): boolean;

package/dist/forms-engine/FocusFirstInvalid.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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).
+ *
+ * Call it after `handleSubmit` settles; capture the form element BEFORE awaiting — the DOM
+ * nulls `event.currentTarget` once dispatch ends, so reading it after an `await` yields `null`:
+ *
+ * ```vue
+ * <form @submit="(event) => {
+ *   const root = event.currentTarget as ParentNode;
+ *   void form.handleSubmit(event).then(() => focusFirstInvalid(root));
+ * }">
+ * ```
+ */
+export declare function focusFirstInvalid(root: ParentNode | null | undefined): HTMLElement | null;

package/dist/forms-engine/FormGlue.d.ts

@@ -0,0 +1,55 @@
+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: readonly 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. It is the bail-out React got
+ * from `useSyncExternalStore`'s selector cache, in one line.
+ *
+ * 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/forms-engine/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): readonly PathKey[];
+/** Formats parsed segments back into the canonical string form (`['rules', 0] → 'rules[0]'`). */
+export declare function formatPath(segments: readonly 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, readonly string[]>>, arrayPath: string, operation: ArrayOperation): Readonly<Record<string, readonly 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/forms-engine/SchemaValidation.d.ts

@@ -0,0 +1,29 @@
+import { ResolveValidationMessage, ValidationMessageCatalogue } from '../foundation/validation';
+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, 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.
+ */
+export declare function runStandardSchema<TValues extends object>(schema: StandardSchemaV1<TValues>, values: TValues, resolveMessage?: ResolveValidationMessage): Record<string, string[]> | Promise<Record<string, 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/forms-engine/StandardSchema.d.ts

@@ -0,0 +1,55 @@
+/** The Standard Schema interface. */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    /** The Standard Schema properties. */
+    readonly '~standard': StandardSchemaV1.Props<Input, Output>;
+}
+export declare namespace StandardSchemaV1 {
+    /** The Standard Schema properties interface. */
+    interface Props<Input = unknown, Output = Input> {
+        /** The version number of the standard. */
+        readonly version: 1;
+        /** The vendor name of the schema library. */
+        readonly vendor: string;
+        /** Validates unknown input values. */
+        readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+        /** Inferred types associated with the schema. */
+        readonly types?: Types<Input, Output> | undefined;
+    }
+    /** The result interface of the validate function. */
+    type Result<Output> = SuccessResult<Output> | FailureResult;
+    /** The result interface if validation succeeds. */
+    interface SuccessResult<Output> {
+        /** The typed output value. */
+        readonly value: Output;
+        /** The non-existent issues. */
+        readonly issues?: undefined;
+    }
+    /** The result interface if validation fails. */
+    interface FailureResult {
+        /** The issues of failed validation. */
+        readonly issues: ReadonlyArray<Issue>;
+    }
+    /** The issue interface of the failure output. */
+    interface Issue {
+        /** The error message of the issue. */
+        readonly message: string;
+        /** The path of the issue, if any. */
+        readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+    }
+    /** The path segment interface of the issue. */
+    interface PathSegment {
+        /** The key representing a path segment. */
+        readonly key: PropertyKey;
+    }
+    /** The Standard Schema types interface. */
+    interface Types<Input = unknown, Output = Input> {
+        /** The input type of the schema. */
+        readonly input: Input;
+        /** The output type of the schema. */
+        readonly output: Output;
+    }
+    /** Infers the input type of a Standard Schema. */
+    type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['input'];
+    /** Infers the output type of a Standard Schema. */
+    type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['output'];
+}

package/dist/forms-engine/SubmitErrors.d.ts

@@ -0,0 +1,33 @@
+import { ApiError } from '../foundation/http';
+import { FieldIssue, ResolveValidationMessage } from '../foundation/validation';
+/** 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, readonly SubmitFieldEntry[]>;
+/** Rewrites a server error path onto a form path — camelCase per property segment (`Rules[0].Destination` → `rules[0].destination`). */
+export declare function defaultMapFieldPath(serverPath: string): string;
+/**
+ * Coerces any thrown value into the SDK `ApiError` — passes through an `ApiError`, wraps
+ * everything else as status `0` (mirrors `/query`'s coercion). `fallbackMessage` is the
+ * message for a throw that carries none of its own (not an `ApiError`, `Error`, or string) —
+ * overridable for i18n; defaults to the English `'Unknown error'`.
+ */
+export declare function toApiError(error: unknown, fallbackMessage?: string): ApiError;
+/** 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, string[]>;
+    /** The coerced failure when it was not fully represented on fields (no or partial path matches); `null` when every mapped path landed. */
+    readonly submitError: ApiError | 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: unknown, mapSubmitError: (error: unknown) => SubmitErrorMap, mapFieldPath: (serverPath: string) => string, isKnownField: (path: string) => boolean, fallbackMessage?: string, resolveMessage?: ResolveValidationMessage): SubmitFailureResolution;

package/dist/forms-engine/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: readonly 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/forms-engine/house/HouseFormCore.d.ts

@@ -0,0 +1,33 @@
+import { ShallowRef } from 'vue';
+import { AppFormOptions, AppFormState } 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: readonly 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 reactive seam that replaces React's `subscribe` + `useSyncExternalStore` pair.
+     */
+    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, string[]>) => void;
+    readonly clearSubmitError: () => void;
+    readonly submit: () => Promise<boolean>;
+    /** Validates without submitting — populates errors, marks touched, resolves client validity. */
+    readonly validate: () => Promise<boolean>;
+    /** 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>(getOptions: () => AppFormOptions<TValues>): HouseFormEngine<TValues>;

package/dist/forms-engine/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>(options: AppFormOptionsSource<TValues>): AppForm<TValues, HouseFormEngine<TValues>>;