@valfuse-node/vue 0.2.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 valfuse-node contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,420 @@
+# @valfuse-node/vue
+
+> Vue 3 adapter for `@valfuse-node` — `useValfuseForm` composable with reactive `formState`, native v-model bindings, and a 1:1 API contract with the React adapter.
+
+```bash
+npm install @valfuse-node/vue @valfuse-node/core
+```
+
+**Peer dependency:** `vue >= 3`
+
+If you want a single install, use the umbrella package:
+
+```bash
+npm install @valfuse-node/core
+```
+
+---
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [`useValfuseForm(options)`](#usevalfuseformoptions)
+- [Reactive `formState`](#reactive-formstate)
+- [`form.register(name)` — Vue v-model binding](#formregistername--vue-v-model-binding)
+- [`form.handleSubmit(onValid)`](#formhandlesubmitonvalid)
+- [`form.setErrors` / `form.clearErrors`](#formseterrors--formclearerrors)
+- [`form.setValue` / `form.getValue` / `form.getValues`](#formsetvalue--formgetvalue--formgetvalues)
+- [`form.trigger`](#formtrigger)
+- [`form.watch(...)` — multi-overload](#formwatch--multi-overload)
+- [`form.reset(values?)`](#formresetvalues)
+- [`form.control`](#formcontrol)
+- [Custom Inputs](#custom-inputs)
+- [API Parity vs React](#api-parity-vs-react)
+- [Type Reference](#type-reference)
+- [Development Usage](#development-usage)
+- [License](#license)
+
+---
+
+## Quick Start
+
+```vue
+<script setup lang="ts">
+import { createSchema } from "@valfuse-node/core";
+import { useValfuseForm } from "@valfuse-node/vue";
+
+const schema = createSchema({
+  email:    { type: "string", rules: [{ name: "required", error: { message: "Required" } }, { name: "email", error: { message: "Invalid" } }] },
+  password: { type: "string", rules: [{ name: "required", error: { message: "Required" } }, { name: "minLength", value: 8, error: { message: "Min 8" } }] },
+});
+
+type LoginValues = { email: string; password: string };
+
+const form = useValfuseForm<LoginValues>({
+  schema,
+  defaultValues: { email: "", password: "" },
+});
+
+async function onSubmit(values: LoginValues) {
+  await loginApi(values);
+}
+</script>
+
+<template>
+  <form @submit="form.handleSubmit(onSubmit)">
+    <input v-bind="form.register('email')" />
+    <span v-if="form.formState.errors.email">
+      {{ form.formState.errors.email.message }}
+    </span>
+
+    <input type="password" v-bind="form.register('password')" />
+    <span v-if="form.formState.errors.password">
+      {{ form.formState.errors.password.message }}
+    </span>
+
+    <button type="submit" :disabled="form.formState.isSubmitting">Log in</button>
+  </form>
+</template>
+```
+
+---
+
+## `useValfuseForm(options)`
+
+```ts
+function useValfuseForm<TFieldValues extends Record<string, unknown>>(
+  options: UseValfuseFormProps<TFieldValues>
+): UseValfuseFormReturn<TFieldValues>;
+```
+
+### Options
+
+```ts
+interface UseValfuseFormProps<TFieldValues> {
+  schema: ValfuseSchema;                                       // required
+  defaultValues: TFieldValues;                                  // required (inferred)
+  mode?: "onSubmit" | "onChange" | "onBlur" | "onTouched" | "all";  // default: "onSubmit"
+  reValidateMode?: "onChange" | "onBlur" | "onSubmit";         // default: "onChange"
+}
+```
+
+| Option | Type | Default | Notes |
+|---|---|---|---|
+| `schema` | `ValfuseSchema` | — (required) | The rule-based schema from `@valfuse-node/form` |
+| `defaultValues` | object literal | — (required) | The generic `TFieldValues` is **inferred** from this |
+| `mode` | union | `"onSubmit"` | When validation first runs |
+| `reValidateMode` | union | `"onChange"` | Mode used after the first submit attempt to re-validate fields the user fixes |
+
+### Return value
+
+```ts
+interface UseValfuseFormReturn<TFieldValues> {
+  formState:   ValfuseFormState<TFieldValues>;   // reactive
+  control:     ValfuseFormControl<TFieldValues>;
+  register:    (name) => { name, modelValue, "onUpdate:modelValue", onBlur };
+  handleSubmit:(onValid) => (e: Event) => Promise<void>;
+  setErrors:   (errors) => void;
+  clearErrors: (fields?) => void;
+  setValue:    (name, value) => void;
+  getValue:    (name) => TFieldValues[TName];
+  getValues:   () => TFieldValues;
+  trigger:     (name?) => boolean;
+  watch:       ValfuseVueWatchFunction<TFieldValues>;
+  reset:       (values?) => void;
+}
+```
+
+---
+
+## Reactive `formState`
+
+`formState` is a `reactive()` proxy — every field is a getter so Vue tracks reads and triggers re-renders.
+
+| Field | Type | Description |
+|---|---|---|
+| `errors` | `Partial<Record<keyof T, ValfuseFieldError>>` | Current field errors |
+| `isSubmitting` | `boolean` | `true` while the async submit handler is running |
+| `isSubmitted` | `boolean` | `true` after the first submit attempt |
+| `isSubmitSuccessful` | `boolean` | `true` if the most recent submit completed without throwing |
+| `submitCount` | `number` | Total submit attempts |
+| `isDirty` | `boolean` | `true` if any field differs from `defaultValues` |
+| `isValid` | `boolean` | `true` when no errors are present |
+| `dirtyFields` | `Partial<Record<keyof T, true>>` | Fields that differ from `defaultValues` |
+| `touchedFields` | `Partial<Record<keyof T, true>>` | Fields the user has blurred |
+| `defaultValues` | `Readonly<T>` | The defaults passed at composable initialization |
+
+```vue
+<template>
+  <div v-if="form.formState.isSubmitting">Saving…</div>
+  <div v-if="form.formState.isDirty">Unsaved changes</div>
+  <pre>{{ form.formState.errors }}</pre>
+</template>
+```
+
+---
+
+## `form.register(name)` — Vue v-model binding
+
+Returns Vue-native v-model props. Use `v-bind` to spread them onto an element.
+
+```vue
+<input v-bind="form.register('email')" />
+<!--
+  expands to:
+    :name="email"
+    :modelValue="email value"
+    @update:modelValue="..."
+    @blur="..."
+-->
+```
+
+The shape is `{ name, modelValue, "onUpdate:modelValue", onBlur }`. This is **intentionally different** from the React adapter — Vue's idiomatic binding is v-model, not onChange.
+
+---
+
+## `form.handleSubmit(onValid)`
+
+```vue
+<script setup lang="ts">
+const onSubmit = form.handleSubmit(async (values) => {
+  // values: TFieldValues  (already transformed + validated)
+  await api.save(values);
+});
+</script>
+
+<template>
+  <form @submit="onSubmit">…</form>
+</template>
+```
+
+The handler:
+1. Calls `e.preventDefault()` on the submit event
+2. Validates the form
+3. If valid → calls `onValid(values)` and sets `isSubmitting = true` for the duration
+4. If invalid → sets `formState.errors` and returns
+
+---
+
+## `form.setErrors` / `form.clearErrors`
+
+```ts
+form.setErrors({ email: { message: "Account exists", code: "auth.duplicate" } });
+form.clearErrors();                       // clear all
+form.clearErrors(["email", "password"]);  // clear specific fields
+```
+
+`form.setErrors` accepts a `SetErrorsInput` — pass either a string (`{ email: "Required" }`) or a `ValfuseError` object (`{ email: { message, code, type } }`). Strings are normalized to objects automatically.
+
+---
+
+## `form.setValue` / `form.getValue` / `form.getValues`
+
+```ts
+form.setValue("email", "alice@example.com");
+
+const current = form.getValue("email");
+const all     = form.getValues();
+```
+
+`getValue` and `getValues` are **Vue-specific extensions** not present in the React adapter. They return snapshots — mutating them has no effect on the form.
+
+---
+
+## `form.trigger`
+
+```ts
+form.trigger();             // all fields
+form.trigger("email");      // one field
+form.trigger(["email", "password"]);  // many
+// returns boolean — true if all triggered fields are valid
+```
+
+Diff-merges results into `formState.errors` without clobbering unrelated field errors.
+
+---
+
+## `form.watch(...)` — multi-overload
+
+```ts
+const all     = form.watch();                          // TFieldValues snapshot
+const email   = form.watch("email");                   // TFieldValues["email"]
+const pair    = form.watch(["email", "name"]);         // Array of values
+
+const unsub = form.watch((values, info) => {           // subscribe to all changes
+  console.log("changed:", info?.name, values);
+});
+
+const unsubField = form.watch("email", (value) => {    // legacy: subscribe to one field
+  console.log("email is now", value);
+});
+
+// later
+unsub();
+unsubField();
+```
+
+> **Tip:** the `watch(callback)` form (global subscription) is preferred over the legacy `watch(name, callback)` form. The legacy form is preserved for backward compatibility.
+
+---
+
+## `form.reset(values?)`
+
+```ts
+form.reset();                  // back to defaultValues
+form.reset({ email: "" });     // partial override
+```
+
+Resets values, errors, touched, dirty, **and** submission state (`isSubmitted`, `isSubmitSuccessful`, `submitCount`).
+
+---
+
+## `form.control`
+
+Same shape as the React adapter's `control` — an opaque object you can pass to a future `<ValfuseController>` Vue equivalent. The `_values`, `_errors`, `_touchedFields` getters always return the latest snapshot.
+
+```ts
+form.control._values;          // current values
+form.control._errors;          // current errors
+form.control._touchedFields;   // ReadonlySet of touched field names
+form.control._updateField(name, value);
+form.control._touchField(name);
+```
+
+---
+
+## Custom Inputs
+
+Vue does not yet ship a `ValfuseController` component, so custom inputs use `form.getValue` / `form.setValue` directly.
+
+```vue
+<script setup lang="ts">
+const role = computed({
+  get: () => form.getValue("role") as string,
+  set: (v) => form.setValue("role", v),
+});
+</script>
+
+<template>
+  <select v-model="role">
+    <option value="admin">Admin</option>
+    <option value="user">User</option>
+  </select>
+</template>
+```
+
+This works because `form.getValue` reads the latest value and `form.setValue` writes through the same internal store that `form.register` uses, so dirty/touched/watch all stay in sync.
+
+---
+
+## API Parity vs React
+
+| Feature | React (`@valfuse-node/react`) | Vue (`@valfuse-node/vue`) |
+|---|---|---|
+| Field binding | `{...form.register('f')}` (JSX spread) | `v-bind="form.register('f')"` |
+| Custom field | `<ValfuseController>` + `form.control` | `getValue` / `setValue` (no controller yet) |
+| Watch snapshot | `form.watch()` | `form.watch()` |
+| Watch subscribe (global) | `form.watch((values, info) => …)` | `form.watch((values, info) => …)` |
+| Watch subscribe (one field) | `form.watch("email", cb)` | `form.watch("email", cb)` (legacy) |
+| Watch subscribe (multi) | `form.watch(["a", "b"], cb)` | — use multiple single-field subscriptions |
+| Manual trigger | `form.trigger()` | `form.trigger()` |
+| Localization runtime | `<LocalizationProvider>` + `useLocalization()` | — not provided; use the underlying `@valfuse-node/localization` package |
+| Mode values | `onSubmit \| onChange \| onBlur \| onTouched \| all` | `onSubmit \| onChange \| onBlur \| onTouched \| all` |
+
+The form contract (`UseValfuseFormReturn`) is **identical at the type level** between React and Vue, so the same schema and the same `defaultValues` can be reused across adapters.
+
+---
+
+## Type Reference
+
+```ts
+import type {
+  UseValfuseFormProps,
+  UseValfuseFormReturn,
+  ValfuseFormMode,
+  ValfuseFormState,
+  ValfuseRegisterReturn,
+} from "@valfuse-node/vue";
+```
+
+---
+
+## Development Usage
+
+### Share a schema across web (React) and mobile (Vue)
+
+```ts
+// schemas/user.ts
+import { createSchema } from "@valfuse-node/form";
+
+export const userSchema = createSchema({
+  name:  { type: "string", rules: [{ name: "required", error: { message: "Required" } }] },
+  email: { type: "string", rules: [{ name: "required", error: { message: "Required" } }, { name: "email", error: { message: "Invalid" } }] },
+});
+
+export type UserValues = { name: string; email: string };
+```
+
+```vue
+<!-- Vue component -->
+<script setup lang="ts">
+import { useValfuseForm } from "@valfuse-node/vue";
+import { userSchema, type UserValues } from "~/schemas/user";
+
+const form = useValfuseForm<UserValues>({
+  schema: userSchema,
+  defaultValues: { name: "", email: "" },
+  mode: "onBlur",
+});
+</script>
+```
+
+### Use a validation mode that matches UX intent
+
+```ts
+// Aggressive — validates on every keystroke
+useValfuseForm({ schema, defaultValues, mode: "onChange" });
+
+// Friendly — validates on blur (recommended for most forms)
+useValfuseForm({ schema, defaultValues, mode: "onBlur" });
+
+// Lazy — only validates on submit
+useValfuseForm({ schema, defaultValues, mode: "onSubmit" });
+```
+
+### Inject server errors
+
+```ts
+async function onSubmit(values: UserValues) {
+  try {
+    await api.saveUser(values);
+  } catch (err) {
+    form.setErrors({
+      email: { message: "Email is already taken", code: "auth.duplicate", type: "server" },
+    });
+  }
+}
+```
+
+### Build a reactive debug panel
+
+```vue
+<script setup lang="ts">
+import { computed } from "vue";
+
+const values = computed(() => form.getValues());
+const dirty  = computed(() => form.formState.dirtyFields);
+</script>
+
+<template>
+  <pre>values: {{ values }}</pre>
+  <pre>dirty:  {{ dirty }}</pre>
+  <pre>valid:  {{ form.formState.isValid }}</pre>
+</template>
+```
+
+---
+
+## License
+
+[MIT](../../LICENSE)

package/dist/index.d.mts

@@ -0,0 +1,123 @@
+import { ValfuseSchema, ValfuseFormErrors, ValfuseDirtyFields, ValfuseTouchedFields, ValfuseFormControl, SetErrorsInput, ValfuseWatchFunction } from '@valfuse-node/form';
+
+/**
+ * Vue-specific watch function with the additional legacy `watch(name, callback)`
+ * form. Mirrors `ValfuseWatchFunction` 1:1 plus:
+ *
+ * ```ts
+ * form.watch("email", (value) => { ... })   // → () => void  (unsubscribe)
+ * ```
+ *
+ * The legacy form is kept for backward compat with pre-contract code; new code
+ * should prefer `form.watch((values, info) => { ... })` so the callback
+ * signature matches the form-domain `ValfuseWatchCallback`.
+ */
+interface ValfuseVueWatchFunction<TFieldValues extends Record<string, unknown>> extends ValfuseWatchFunction<TFieldValues> {
+    (name: keyof TFieldValues & string, callback: (value: unknown) => void): () => void;
+}
+/**
+ * Validation trigger mode.
+ *
+ * Mirrors the React adapter and the form-domain contract exactly.
+ * `onTouched` is supported by React; for Vue we currently support the same
+ * three core modes. Extend when needed.
+ */
+type ValfuseFormMode = "onSubmit" | "onChange" | "onBlur" | "onTouched" | "all";
+/**
+ * Options for useValfuseForm.
+ *
+ * `TFieldValues` is the **values shape** (not the schema shape) — inferred
+ * from `defaultValues`. This matches the React adapter and the form-domain
+ * contract, so a consumer can swap frameworks without rewriting the call site.
+ */
+interface UseValfuseFormProps<TFieldValues extends Record<string, unknown>> {
+    schema: ValfuseSchema;
+    defaultValues: TFieldValues;
+    mode?: ValfuseFormMode;
+    /** Mode used to re-validate a field after the first submit attempt. */
+    reValidateMode?: ValfuseFormMode;
+}
+/**
+ * Reactive form state exposed by useValfuseForm.
+ *
+ * Shape mirrors the form-domain `ValfuseFormState` exactly so a consumer can
+ * swap adapters without re-learning the API. The `readonly` modifiers are
+ * documentation — Vue cannot enforce them at runtime on a reactive proxy,
+ * but consumers should treat the state as read-only.
+ */
+interface ValfuseFormState<TFieldValues extends Record<string, unknown>> {
+    readonly errors: ValfuseFormErrors<TFieldValues>;
+    readonly isSubmitting: boolean;
+    readonly isSubmitted: boolean;
+    readonly isSubmitSuccessful: boolean;
+    readonly submitCount: number;
+    readonly isDirty: boolean;
+    readonly isValid: boolean;
+    readonly dirtyFields: ValfuseDirtyFields<TFieldValues>;
+    readonly touchedFields: ValfuseTouchedFields<TFieldValues>;
+    readonly defaultValues: Readonly<TFieldValues>;
+}
+/**
+ * Props returned by `form.register(name)` for the Vue adapter.
+ *
+ * Shape is Vue-native (v-model): spread the result onto an element with
+ * `v-bind` and `v-model` will work out of the box. This is intentionally
+ * different from the React adapter's `ValfuseRegisterReturn` — Vue's
+ * idiomatic binding shape uses `modelValue` + `onUpdate:modelValue`.
+ */
+interface ValfuseRegisterReturn {
+    name: string;
+    modelValue: unknown;
+    "onUpdate:modelValue": (value: unknown) => void;
+    onBlur: () => void;
+}
+/**
+ * Return type of useValfuseForm.
+ *
+ * Mirrors the form-domain `UseValfuseFormReturn` contract, with two
+ * adapter-specific extensions:
+ *  - `register` returns the Vue-native `ValfuseRegisterReturn` (v-model shape).
+ *  - `getValue` and `getValues` are convenience getters not present in React.
+ *
+ * All other members match the React contract 1:1. In particular, `control`
+ * is the same shape used by React's `<ValfuseController>` — a future
+ * Vue equivalent component will accept it identically.
+ */
+interface UseValfuseFormReturn<TFieldValues extends Record<string, unknown>> {
+    formState: ValfuseFormState<TFieldValues>;
+    control: ValfuseFormControl<TFieldValues>;
+    register: (name: keyof TFieldValues & string) => ValfuseRegisterReturn;
+    handleSubmit: (fn: (values: TFieldValues) => Promise<void> | void) => (e: Event) => Promise<void>;
+    setErrors: (errors: SetErrorsInput) => void;
+    clearErrors: (fields?: Array<keyof TFieldValues & string>) => void;
+    setValue: (name: keyof TFieldValues & string, value: unknown) => void;
+    trigger: (name?: keyof TFieldValues & string | Array<keyof TFieldValues & string>) => boolean;
+    watch: ValfuseVueWatchFunction<TFieldValues>;
+    reset: (values?: Partial<TFieldValues>) => void;
+    /** Vue-specific extension: read a single field value. */
+    getValue: (name: keyof TFieldValues & string) => unknown;
+    /** Vue-specific extension: read all field values. */
+    getValues: () => TFieldValues;
+}
+
+/**
+ * useValfuseForm — Vue composable.
+ *
+ * Public API contract matches the React adapter and the form-domain
+ * `UseValfuseFormReturn` interface. The two adapter-specific differences:
+ *   1. `register()` returns Vue-native v-model props
+ *      (`modelValue` + `onUpdate:modelValue`).
+ *   2. `getValue(name)` and `getValues()` are convenience getters that
+ *      the React adapter does not expose.
+ *
+ * Internal state uses Sets for O(1) add/delete on dirty/touched tracking,
+ * but the public `formState` exposes them as Record-shaped
+ * `{ [K]?: true }` to match the form contract.
+ *
+ * Usage:
+ *   const form = useValfuseForm({ schema, defaultValues })
+ *   <input v-bind="form.register('email')" />
+ */
+declare function useValfuseForm<TFieldValues extends Record<string, unknown>>(options: UseValfuseFormProps<TFieldValues>): UseValfuseFormReturn<TFieldValues>;
+
+export { type UseValfuseFormProps, type UseValfuseFormReturn, type ValfuseFormMode, type ValfuseFormState, type ValfuseRegisterReturn, useValfuseForm };

package/dist/index.d.ts

@@ -0,0 +1,123 @@
+import { ValfuseSchema, ValfuseFormErrors, ValfuseDirtyFields, ValfuseTouchedFields, ValfuseFormControl, SetErrorsInput, ValfuseWatchFunction } from '@valfuse-node/form';
+
+/**
+ * Vue-specific watch function with the additional legacy `watch(name, callback)`
+ * form. Mirrors `ValfuseWatchFunction` 1:1 plus:
+ *
+ * ```ts
+ * form.watch("email", (value) => { ... })   // → () => void  (unsubscribe)
+ * ```
+ *
+ * The legacy form is kept for backward compat with pre-contract code; new code
+ * should prefer `form.watch((values, info) => { ... })` so the callback
+ * signature matches the form-domain `ValfuseWatchCallback`.
+ */
+interface ValfuseVueWatchFunction<TFieldValues extends Record<string, unknown>> extends ValfuseWatchFunction<TFieldValues> {
+    (name: keyof TFieldValues & string, callback: (value: unknown) => void): () => void;
+}
+/**
+ * Validation trigger mode.
+ *
+ * Mirrors the React adapter and the form-domain contract exactly.
+ * `onTouched` is supported by React; for Vue we currently support the same
+ * three core modes. Extend when needed.
+ */
+type ValfuseFormMode = "onSubmit" | "onChange" | "onBlur" | "onTouched" | "all";
+/**
+ * Options for useValfuseForm.
+ *
+ * `TFieldValues` is the **values shape** (not the schema shape) — inferred
+ * from `defaultValues`. This matches the React adapter and the form-domain
+ * contract, so a consumer can swap frameworks without rewriting the call site.
+ */
+interface UseValfuseFormProps<TFieldValues extends Record<string, unknown>> {
+    schema: ValfuseSchema;
+    defaultValues: TFieldValues;
+    mode?: ValfuseFormMode;
+    /** Mode used to re-validate a field after the first submit attempt. */
+    reValidateMode?: ValfuseFormMode;
+}
+/**
+ * Reactive form state exposed by useValfuseForm.
+ *
+ * Shape mirrors the form-domain `ValfuseFormState` exactly so a consumer can
+ * swap adapters without re-learning the API. The `readonly` modifiers are
+ * documentation — Vue cannot enforce them at runtime on a reactive proxy,
+ * but consumers should treat the state as read-only.
+ */
+interface ValfuseFormState<TFieldValues extends Record<string, unknown>> {
+    readonly errors: ValfuseFormErrors<TFieldValues>;
+    readonly isSubmitting: boolean;
+    readonly isSubmitted: boolean;
+    readonly isSubmitSuccessful: boolean;
+    readonly submitCount: number;
+    readonly isDirty: boolean;
+    readonly isValid: boolean;
+    readonly dirtyFields: ValfuseDirtyFields<TFieldValues>;
+    readonly touchedFields: ValfuseTouchedFields<TFieldValues>;
+    readonly defaultValues: Readonly<TFieldValues>;
+}
+/**
+ * Props returned by `form.register(name)` for the Vue adapter.
+ *
+ * Shape is Vue-native (v-model): spread the result onto an element with
+ * `v-bind` and `v-model` will work out of the box. This is intentionally
+ * different from the React adapter's `ValfuseRegisterReturn` — Vue's
+ * idiomatic binding shape uses `modelValue` + `onUpdate:modelValue`.
+ */
+interface ValfuseRegisterReturn {
+    name: string;
+    modelValue: unknown;
+    "onUpdate:modelValue": (value: unknown) => void;
+    onBlur: () => void;
+}
+/**
+ * Return type of useValfuseForm.
+ *
+ * Mirrors the form-domain `UseValfuseFormReturn` contract, with two
+ * adapter-specific extensions:
+ *  - `register` returns the Vue-native `ValfuseRegisterReturn` (v-model shape).
+ *  - `getValue` and `getValues` are convenience getters not present in React.
+ *
+ * All other members match the React contract 1:1. In particular, `control`
+ * is the same shape used by React's `<ValfuseController>` — a future
+ * Vue equivalent component will accept it identically.
+ */
+interface UseValfuseFormReturn<TFieldValues extends Record<string, unknown>> {
+    formState: ValfuseFormState<TFieldValues>;
+    control: ValfuseFormControl<TFieldValues>;
+    register: (name: keyof TFieldValues & string) => ValfuseRegisterReturn;
+    handleSubmit: (fn: (values: TFieldValues) => Promise<void> | void) => (e: Event) => Promise<void>;
+    setErrors: (errors: SetErrorsInput) => void;
+    clearErrors: (fields?: Array<keyof TFieldValues & string>) => void;
+    setValue: (name: keyof TFieldValues & string, value: unknown) => void;
+    trigger: (name?: keyof TFieldValues & string | Array<keyof TFieldValues & string>) => boolean;
+    watch: ValfuseVueWatchFunction<TFieldValues>;
+    reset: (values?: Partial<TFieldValues>) => void;
+    /** Vue-specific extension: read a single field value. */
+    getValue: (name: keyof TFieldValues & string) => unknown;
+    /** Vue-specific extension: read all field values. */
+    getValues: () => TFieldValues;
+}
+
+/**
+ * useValfuseForm — Vue composable.
+ *
+ * Public API contract matches the React adapter and the form-domain
+ * `UseValfuseFormReturn` interface. The two adapter-specific differences:
+ *   1. `register()` returns Vue-native v-model props
+ *      (`modelValue` + `onUpdate:modelValue`).
+ *   2. `getValue(name)` and `getValues()` are convenience getters that
+ *      the React adapter does not expose.
+ *
+ * Internal state uses Sets for O(1) add/delete on dirty/touched tracking,
+ * but the public `formState` exposes them as Record-shaped
+ * `{ [K]?: true }` to match the form contract.
+ *
+ * Usage:
+ *   const form = useValfuseForm({ schema, defaultValues })
+ *   <input v-bind="form.register('email')" />
+ */
+declare function useValfuseForm<TFieldValues extends Record<string, unknown>>(options: UseValfuseFormProps<TFieldValues>): UseValfuseFormReturn<TFieldValues>;
+
+export { type UseValfuseFormProps, type UseValfuseFormReturn, type ValfuseFormMode, type ValfuseFormState, type ValfuseRegisterReturn, useValfuseForm };

package/dist/index.js

@@ -0,0 +1,291 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  useValfuseForm: () => useValfuseForm
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/composables/use-valfuse-form.ts
+var import_vue = require("vue");
+var import_form = require("@valfuse-node/form");
+function useValfuseForm(options) {
+  const { schema, defaultValues, mode = "onSubmit", reValidateMode = "onChange" } = options;
+  const values = (0, import_vue.reactive)({ ...defaultValues });
+  const errors = (0, import_vue.ref)({});
+  const isSubmitting = (0, import_vue.ref)(false);
+  const isSubmitted = (0, import_vue.ref)(false);
+  const isSubmitSuccessful = (0, import_vue.ref)(false);
+  const submitCount = (0, import_vue.ref)(0);
+  const dirtySet = (0, import_vue.shallowRef)(/* @__PURE__ */ new Set());
+  const touchedSet = (0, import_vue.shallowRef)(/* @__PURE__ */ new Set());
+  const fieldWatchers = /* @__PURE__ */ new Map();
+  const globalWatchers = /* @__PURE__ */ new Set();
+  function runValidation() {
+    const typed = (0, import_form.transformValues)(schema, values);
+    return (0, import_form.validateSchema)(schema, typed);
+  }
+  function setToRecord(set) {
+    const out = {};
+    for (const k of set) out[k] = true;
+    return out;
+  }
+  function markDirty(key, newValue) {
+    const dirty = new Set(dirtySet.value);
+    if (newValue !== defaultValues[key]) {
+      dirty.add(key);
+    } else {
+      dirty.delete(key);
+    }
+    dirtySet.value = dirty;
+  }
+  function markTouched(key) {
+    const touched = new Set(touchedSet.value);
+    touched.add(key);
+    touchedSet.value = touched;
+  }
+  function notifyWatchers(name, value) {
+    fieldWatchers.get(name)?.forEach((cb) => cb(value));
+    if (globalWatchers.size > 0) {
+      const info = { name, type: "change" };
+      globalWatchers.forEach(
+        (cb) => cb(values, info)
+      );
+    }
+  }
+  function register(name) {
+    const key = String(name);
+    return {
+      name: key,
+      modelValue: values[key],
+      "onUpdate:modelValue": (value) => {
+        values[key] = value;
+        markDirty(key, value);
+        notifyWatchers(key, value);
+        if (mode === "onChange" || isSubmitted.value && reValidateMode === "onChange") {
+          errors.value = runValidation();
+        }
+      },
+      onBlur: () => {
+        markTouched(key);
+        if (mode === "onBlur" || isSubmitted.value && reValidateMode === "onBlur") {
+          errors.value = runValidation();
+        }
+      }
+    };
+  }
+  async function runSubmit(fn) {
+    isSubmitted.value = true;
+    submitCount.value += 1;
+    const validationErrors = runValidation();
+    if (Object.keys(validationErrors).length > 0) {
+      errors.value = validationErrors;
+      isSubmitSuccessful.value = false;
+      return;
+    }
+    errors.value = {};
+    isSubmitting.value = true;
+    try {
+      const typed = (0, import_form.transformValues)(schema, values);
+      await fn(typed);
+      isSubmitSuccessful.value = true;
+    } catch {
+      isSubmitSuccessful.value = false;
+      throw new Error("Submit handler failed");
+    } finally {
+      isSubmitting.value = false;
+    }
+  }
+  function handleSubmit(fn) {
+    return async (e) => {
+      e.preventDefault?.();
+      await runSubmit(fn);
+    };
+  }
+  function setErrors(input) {
+    const normalized = {};
+    for (const [k, v] of Object.entries(input)) {
+      if (v !== void 0) normalized[k] = (0, import_form.normalizeError)(v);
+    }
+    errors.value = { ...errors.value, ...normalized };
+  }
+  function clearErrors(fields) {
+    if (!fields) {
+      errors.value = {};
+      return;
+    }
+    const next = { ...errors.value };
+    for (const f of fields) delete next[f];
+    errors.value = next;
+  }
+  function setValue(name, value) {
+    const key = String(name);
+    values[key] = value;
+    markDirty(key, value);
+    notifyWatchers(key, value);
+  }
+  function getValue(name) {
+    return values[String(name)];
+  }
+  function getValues() {
+    return { ...values };
+  }
+  function trigger(name) {
+    const validationErrors = runValidation();
+    const fieldsToValidate = name === void 0 ? Object.keys(schema) : Array.isArray(name) ? name : [name];
+    let allValid = true;
+    const next = { ...errors.value };
+    let changed = false;
+    for (const f of fieldsToValidate) {
+      const err = validationErrors[f];
+      if (err) {
+        allValid = false;
+        const prev = next[f];
+        if (!prev || prev.message !== err.message || prev.type !== err.type || prev.code !== err.code) {
+          next[f] = err;
+          changed = true;
+        }
+      } else {
+        if (f in next) {
+          delete next[f];
+          changed = true;
+        }
+      }
+    }
+    if (changed) errors.value = next;
+    return allValid;
+  }
+  function reset(overrides) {
+    const next = overrides ?? defaultValues;
+    for (const k of Object.keys(values)) values[k] = next[k] ?? void 0;
+    errors.value = {};
+    isSubmitted.value = false;
+    isSubmitSuccessful.value = false;
+    submitCount.value = 0;
+    dirtySet.value = /* @__PURE__ */ new Set();
+    touchedSet.value = /* @__PURE__ */ new Set();
+  }
+  function watch(arg, legacyCb) {
+    if (legacyCb !== void 0) {
+      if (typeof arg !== "string" && !Array.isArray(arg)) {
+        throw new TypeError("watch(name, cb): name must be a field name string");
+      }
+      const name = String(arg);
+      let bucket = fieldWatchers.get(name);
+      if (!bucket) {
+        bucket = /* @__PURE__ */ new Set();
+        fieldWatchers.set(name, bucket);
+      }
+      bucket.add(legacyCb);
+      return () => bucket.delete(legacyCb);
+    }
+    if (typeof arg === "function") {
+      const cb = arg;
+      globalWatchers.add(cb);
+      return () => {
+        globalWatchers.delete(cb);
+      };
+    }
+    if (Array.isArray(arg)) {
+      return arg.map((n) => values[String(n)]);
+    }
+    if (typeof arg === "string") {
+      return values[arg];
+    }
+    return { ...values };
+  }
+  const control = (0, import_vue.reactive)({
+    _values: values,
+    get _errors() {
+      return errors.value;
+    },
+    get _touchedFields() {
+      return touchedSet.value;
+    },
+    _updateField: (name, value) => {
+      const key = String(name);
+      values[key] = value;
+      markDirty(key, value);
+      notifyWatchers(key, value);
+    },
+    _touchField: (name) => {
+      markTouched(String(name));
+    }
+  });
+  const dirtyFieldsRecord = (0, import_vue.computed)(
+    () => setToRecord(dirtySet.value)
+  );
+  const touchedFieldsRecord = (0, import_vue.computed)(
+    () => setToRecord(touchedSet.value)
+  );
+  const isDirtyComputed = (0, import_vue.computed)(() => dirtySet.value.size > 0);
+  const isValidComputed = (0, import_vue.computed)(() => Object.keys(errors.value).length === 0);
+  const formState = (0, import_vue.reactive)({
+    get errors() {
+      return errors.value;
+    },
+    get isSubmitting() {
+      return isSubmitting.value;
+    },
+    get isSubmitted() {
+      return isSubmitted.value;
+    },
+    get isSubmitSuccessful() {
+      return isSubmitSuccessful.value;
+    },
+    get submitCount() {
+      return submitCount.value;
+    },
+    get isDirty() {
+      return isDirtyComputed.value;
+    },
+    get isValid() {
+      return isValidComputed.value;
+    },
+    get dirtyFields() {
+      return dirtyFieldsRecord.value;
+    },
+    get touchedFields() {
+      return touchedFieldsRecord.value;
+    },
+    get defaultValues() {
+      return { ...defaultValues };
+    }
+  });
+  return {
+    formState,
+    control,
+    register,
+    handleSubmit,
+    setErrors,
+    clearErrors,
+    setValue,
+    trigger,
+    getValue,
+    getValues,
+    reset,
+    watch
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useValfuseForm
+});

package/dist/index.mjs

@@ -0,0 +1,264 @@
+// src/composables/use-valfuse-form.ts
+import { computed, reactive, ref, shallowRef } from "vue";
+import { validateSchema, transformValues, normalizeError } from "@valfuse-node/form";
+function useValfuseForm(options) {
+  const { schema, defaultValues, mode = "onSubmit", reValidateMode = "onChange" } = options;
+  const values = reactive({ ...defaultValues });
+  const errors = ref({});
+  const isSubmitting = ref(false);
+  const isSubmitted = ref(false);
+  const isSubmitSuccessful = ref(false);
+  const submitCount = ref(0);
+  const dirtySet = shallowRef(/* @__PURE__ */ new Set());
+  const touchedSet = shallowRef(/* @__PURE__ */ new Set());
+  const fieldWatchers = /* @__PURE__ */ new Map();
+  const globalWatchers = /* @__PURE__ */ new Set();
+  function runValidation() {
+    const typed = transformValues(schema, values);
+    return validateSchema(schema, typed);
+  }
+  function setToRecord(set) {
+    const out = {};
+    for (const k of set) out[k] = true;
+    return out;
+  }
+  function markDirty(key, newValue) {
+    const dirty = new Set(dirtySet.value);
+    if (newValue !== defaultValues[key]) {
+      dirty.add(key);
+    } else {
+      dirty.delete(key);
+    }
+    dirtySet.value = dirty;
+  }
+  function markTouched(key) {
+    const touched = new Set(touchedSet.value);
+    touched.add(key);
+    touchedSet.value = touched;
+  }
+  function notifyWatchers(name, value) {
+    fieldWatchers.get(name)?.forEach((cb) => cb(value));
+    if (globalWatchers.size > 0) {
+      const info = { name, type: "change" };
+      globalWatchers.forEach(
+        (cb) => cb(values, info)
+      );
+    }
+  }
+  function register(name) {
+    const key = String(name);
+    return {
+      name: key,
+      modelValue: values[key],
+      "onUpdate:modelValue": (value) => {
+        values[key] = value;
+        markDirty(key, value);
+        notifyWatchers(key, value);
+        if (mode === "onChange" || isSubmitted.value && reValidateMode === "onChange") {
+          errors.value = runValidation();
+        }
+      },
+      onBlur: () => {
+        markTouched(key);
+        if (mode === "onBlur" || isSubmitted.value && reValidateMode === "onBlur") {
+          errors.value = runValidation();
+        }
+      }
+    };
+  }
+  async function runSubmit(fn) {
+    isSubmitted.value = true;
+    submitCount.value += 1;
+    const validationErrors = runValidation();
+    if (Object.keys(validationErrors).length > 0) {
+      errors.value = validationErrors;
+      isSubmitSuccessful.value = false;
+      return;
+    }
+    errors.value = {};
+    isSubmitting.value = true;
+    try {
+      const typed = transformValues(schema, values);
+      await fn(typed);
+      isSubmitSuccessful.value = true;
+    } catch {
+      isSubmitSuccessful.value = false;
+      throw new Error("Submit handler failed");
+    } finally {
+      isSubmitting.value = false;
+    }
+  }
+  function handleSubmit(fn) {
+    return async (e) => {
+      e.preventDefault?.();
+      await runSubmit(fn);
+    };
+  }
+  function setErrors(input) {
+    const normalized = {};
+    for (const [k, v] of Object.entries(input)) {
+      if (v !== void 0) normalized[k] = normalizeError(v);
+    }
+    errors.value = { ...errors.value, ...normalized };
+  }
+  function clearErrors(fields) {
+    if (!fields) {
+      errors.value = {};
+      return;
+    }
+    const next = { ...errors.value };
+    for (const f of fields) delete next[f];
+    errors.value = next;
+  }
+  function setValue(name, value) {
+    const key = String(name);
+    values[key] = value;
+    markDirty(key, value);
+    notifyWatchers(key, value);
+  }
+  function getValue(name) {
+    return values[String(name)];
+  }
+  function getValues() {
+    return { ...values };
+  }
+  function trigger(name) {
+    const validationErrors = runValidation();
+    const fieldsToValidate = name === void 0 ? Object.keys(schema) : Array.isArray(name) ? name : [name];
+    let allValid = true;
+    const next = { ...errors.value };
+    let changed = false;
+    for (const f of fieldsToValidate) {
+      const err = validationErrors[f];
+      if (err) {
+        allValid = false;
+        const prev = next[f];
+        if (!prev || prev.message !== err.message || prev.type !== err.type || prev.code !== err.code) {
+          next[f] = err;
+          changed = true;
+        }
+      } else {
+        if (f in next) {
+          delete next[f];
+          changed = true;
+        }
+      }
+    }
+    if (changed) errors.value = next;
+    return allValid;
+  }
+  function reset(overrides) {
+    const next = overrides ?? defaultValues;
+    for (const k of Object.keys(values)) values[k] = next[k] ?? void 0;
+    errors.value = {};
+    isSubmitted.value = false;
+    isSubmitSuccessful.value = false;
+    submitCount.value = 0;
+    dirtySet.value = /* @__PURE__ */ new Set();
+    touchedSet.value = /* @__PURE__ */ new Set();
+  }
+  function watch(arg, legacyCb) {
+    if (legacyCb !== void 0) {
+      if (typeof arg !== "string" && !Array.isArray(arg)) {
+        throw new TypeError("watch(name, cb): name must be a field name string");
+      }
+      const name = String(arg);
+      let bucket = fieldWatchers.get(name);
+      if (!bucket) {
+        bucket = /* @__PURE__ */ new Set();
+        fieldWatchers.set(name, bucket);
+      }
+      bucket.add(legacyCb);
+      return () => bucket.delete(legacyCb);
+    }
+    if (typeof arg === "function") {
+      const cb = arg;
+      globalWatchers.add(cb);
+      return () => {
+        globalWatchers.delete(cb);
+      };
+    }
+    if (Array.isArray(arg)) {
+      return arg.map((n) => values[String(n)]);
+    }
+    if (typeof arg === "string") {
+      return values[arg];
+    }
+    return { ...values };
+  }
+  const control = reactive({
+    _values: values,
+    get _errors() {
+      return errors.value;
+    },
+    get _touchedFields() {
+      return touchedSet.value;
+    },
+    _updateField: (name, value) => {
+      const key = String(name);
+      values[key] = value;
+      markDirty(key, value);
+      notifyWatchers(key, value);
+    },
+    _touchField: (name) => {
+      markTouched(String(name));
+    }
+  });
+  const dirtyFieldsRecord = computed(
+    () => setToRecord(dirtySet.value)
+  );
+  const touchedFieldsRecord = computed(
+    () => setToRecord(touchedSet.value)
+  );
+  const isDirtyComputed = computed(() => dirtySet.value.size > 0);
+  const isValidComputed = computed(() => Object.keys(errors.value).length === 0);
+  const formState = reactive({
+    get errors() {
+      return errors.value;
+    },
+    get isSubmitting() {
+      return isSubmitting.value;
+    },
+    get isSubmitted() {
+      return isSubmitted.value;
+    },
+    get isSubmitSuccessful() {
+      return isSubmitSuccessful.value;
+    },
+    get submitCount() {
+      return submitCount.value;
+    },
+    get isDirty() {
+      return isDirtyComputed.value;
+    },
+    get isValid() {
+      return isValidComputed.value;
+    },
+    get dirtyFields() {
+      return dirtyFieldsRecord.value;
+    },
+    get touchedFields() {
+      return touchedFieldsRecord.value;
+    },
+    get defaultValues() {
+      return { ...defaultValues };
+    }
+  });
+  return {
+    formState,
+    control,
+    register,
+    handleSubmit,
+    setErrors,
+    clearErrors,
+    setValue,
+    trigger,
+    getValue,
+    getValues,
+    reset,
+    watch
+  };
+}
+export {
+  useValfuseForm
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@valfuse-node/vue",
+  "version": "0.2.0",
+  "description": "Vue adapter for valfuse-node — useValfuseForm composable",
+  "license": "MIT",
+  "sideEffects": false,
+  "keywords": ["validation", "schema", "form", "vue", "vue3", "composable", "typescript", "valfuse"],
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean --external vue --external @valfuse-node/form",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch --external vue --external @valfuse-node/form",
+    "lint": "eslint src",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist coverage"
+  },
+  "dependencies": {
+    "@valfuse-node/form": "*"
+  },
+  "peerDependencies": {
+    "vue": ">=3"
+  },
+  "publishConfig": { "access": "public" },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "latest",
+    "@vitest/coverage-v8": "latest",
+    "@vue/test-utils": "latest",
+    "vitest": "latest",
+    "vue": "^3"
+  }
+}
+