@gunubin/vorm-react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 gunubin
+
+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,82 @@
+# @gunubin/vorm-react
+
+React hooks for vorm — `useForm` and `useField` with per-field subscriptions via `useSyncExternalStore`.
+
+Part of the [vorm](https://github.com/gunubin/vorm) monorepo.
+
+## Install
+
+```bash
+npm install @gunubin/vorm-core @gunubin/vorm-react
+```
+
+## Quick Start
+
+```tsx
+import { useForm, useField } from '@gunubin/vorm-react';
+
+function LoginForm() {
+  const form = useForm(loginSchema, {
+    defaultValues: { email: '', password: '' },
+    mode: 'onBlur',
+  });
+
+  const email = useField(form, 'email');
+  const password = useField(form, 'password');
+
+  return (
+    <form onSubmit={form.handleSubmit((values) => {
+      // values.email is Brand<string, 'Email'>
+      login(values.email, values.password);
+    })}>
+      <input value={email.value} onChange={(e) => email.onChange(e.target.value)} onBlur={email.onBlur} />
+      {email.error && <span>{email.error.message}</span>}
+
+      <input type="password" value={password.value} onChange={(e) => password.onChange(e.target.value)} onBlur={password.onBlur} />
+      {password.error && <span>{password.error.message}</span>}
+
+      <button type="submit" disabled={form.isSubmitting}>Log in</button>
+    </form>
+  );
+}
+```
+
+## Why `useField`?
+
+`useField(form, 'email')` subscribes **only** to the email field's state. When the password changes, the email input does not re-render.
+
+`form.field('email')` also works but reads from the form-level snapshot, so it re-renders with every field change. Use `useField` for performance-critical forms.
+
+## Validation Modes
+
+| Mode | Behavior |
+|------|----------|
+| `onSubmit` | Validate only on submit (default) |
+| `onBlur` | Validate when a field loses focus |
+| `onChange` | Validate on every value change |
+| `onTouched` | Validate on first blur, then re-validate on change |
+
+## Async Validation
+
+```ts
+const form = useForm(schema, {
+  defaultValues: { email: '' },
+  asyncValidators: {
+    email: {
+      validate: async (value) => {
+        const taken = await checkEmailExists(value);
+        if (taken) return { code: 'TAKEN', message: 'Already registered' };
+        return null;
+      },
+      on: 'blur',
+      debounceMs: 300,
+    },
+  },
+});
+```
+
+For full documentation, see the [vorm README](https://github.com/gunubin/vorm#readme).
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,519 @@
+"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, {
+  createFormStore: () => createFormStore,
+  useField: () => useField,
+  useForm: () => useForm
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/use-form.ts
+var import_react = require("react");
+var import_vorm_core = require("@gunubin/vorm-core");
+
+// src/form-store.ts
+function createFormStore(initialState) {
+  let state = initialState;
+  let snapshot = state;
+  const listeners = /* @__PURE__ */ new Set();
+  const fieldListeners = /* @__PURE__ */ new Map();
+  const fieldSnapshotCache = /* @__PURE__ */ new Map();
+  function emit(changedFields) {
+    snapshot = { ...state };
+    for (const listener of listeners) {
+      listener();
+    }
+    if (changedFields) {
+      for (const name of changedFields) {
+        fieldSnapshotCache.delete(name);
+        const set = fieldListeners.get(name);
+        if (set) {
+          for (const listener of set) {
+            listener();
+          }
+        }
+      }
+    } else {
+      fieldSnapshotCache.clear();
+      for (const [, set] of fieldListeners) {
+        for (const listener of set) {
+          listener();
+        }
+      }
+    }
+  }
+  return {
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    getSnapshot() {
+      return snapshot;
+    },
+    subscribeField(name, listener) {
+      if (!fieldListeners.has(name)) {
+        fieldListeners.set(name, /* @__PURE__ */ new Set());
+      }
+      fieldListeners.get(name).add(listener);
+      return () => {
+        fieldListeners.get(name).delete(listener);
+      };
+    },
+    getFieldSnapshot(name) {
+      const cached = fieldSnapshotCache.get(name);
+      if (cached) return cached;
+      const snap = {
+        value: state.values[name],
+        error: state.errors[name] ?? null,
+        isTouched: state.touchedFields[name] ?? false
+      };
+      fieldSnapshotCache.set(name, snap);
+      return snap;
+    },
+    getState() {
+      return state;
+    },
+    setFieldValue(name, value) {
+      state = {
+        ...state,
+        values: { ...state.values, [name]: value },
+        isDirty: true
+      };
+      emit([name]);
+    },
+    setFieldTouched(name) {
+      state = {
+        ...state,
+        touchedFields: { ...state.touchedFields, [name]: true }
+      };
+      emit([name]);
+    },
+    setFieldError(name, error) {
+      state = {
+        ...state,
+        errors: { ...state.errors, [name]: error }
+      };
+      emit([name]);
+    },
+    clearFieldError(name) {
+      if (name) {
+        const next = { ...state.errors };
+        delete next[name];
+        state = { ...state, errors: next };
+        emit([name]);
+      } else {
+        state = { ...state, errors: {} };
+        emit();
+      }
+    },
+    setErrors(errors) {
+      state = { ...state, errors };
+      emit();
+    },
+    setIsSubmitting(value) {
+      state = { ...state, isSubmitting: value };
+      emit();
+    },
+    setIsValidating(value) {
+      state = { ...state, isValidating: value };
+      emit();
+    },
+    reset(values) {
+      state = {
+        values,
+        errors: {},
+        isDirty: false,
+        isSubmitting: false,
+        isValidating: false,
+        touchedFields: {}
+      };
+      emit();
+    }
+  };
+}
+
+// src/use-form.ts
+function useForm(schema, options) {
+  const { defaultValues, mode = "onSubmit", asyncValidators } = options;
+  const storeRef = (0, import_react.useRef)(null);
+  if (storeRef.current === null) {
+    storeRef.current = createFormStore({
+      values: { ...defaultValues },
+      errors: {},
+      isDirty: false,
+      isSubmitting: false,
+      isValidating: false,
+      touchedFields: {}
+    });
+  }
+  const store = storeRef.current;
+  const state = (0, import_react.useSyncExternalStore)(store.subscribe, store.getSnapshot, store.getSnapshot);
+  const defaultValuesRef = (0, import_react.useRef)(defaultValues);
+  const asyncValidatorsRef = (0, import_react.useRef)(asyncValidators);
+  asyncValidatorsRef.current = asyncValidators;
+  const validatingFieldsRef = (0, import_react.useRef)(/* @__PURE__ */ new Set());
+  const abortControllersRef = (0, import_react.useRef)(/* @__PURE__ */ new Map());
+  const debounceTimersRef = (0, import_react.useRef)(/* @__PURE__ */ new Map());
+  const isValid = Object.keys(state.errors).length === 0;
+  const runAsyncValidation = (0, import_react.useCallback)(
+    async (name, value) => {
+      const asyncValidator = asyncValidatorsRef.current?.[name];
+      if (!asyncValidator) return null;
+      const prevController = abortControllersRef.current.get(name);
+      if (prevController) prevController.abort();
+      const controller = new AbortController();
+      abortControllersRef.current.set(name, controller);
+      validatingFieldsRef.current.add(name);
+      store.setIsValidating(true);
+      try {
+        const error = await asyncValidator.validate(value);
+        if (controller.signal.aborted) return null;
+        if (error) {
+          store.setFieldError(name, error);
+        } else {
+          store.clearFieldError(name);
+        }
+        return error;
+      } finally {
+        if (!controller.signal.aborted) {
+          validatingFieldsRef.current.delete(name);
+          abortControllersRef.current.delete(name);
+          if (validatingFieldsRef.current.size === 0) {
+            store.setIsValidating(false);
+          }
+        }
+      }
+    },
+    [store]
+  );
+  const scheduleAsyncValidation = (0, import_react.useCallback)(
+    (name, value, trigger) => {
+      const asyncValidator = asyncValidatorsRef.current?.[name];
+      if (!asyncValidator) return;
+      const on = asyncValidator.on ?? "blur";
+      if (on !== trigger) return;
+      const fieldSchema = schema.fields[name];
+      if (fieldSchema) {
+        const formMessages = schema.messages?.[name];
+        const syncError = (0, import_vorm_core.validateField)(value, fieldSchema, formMessages);
+        if (syncError) return;
+      }
+      const existingTimer = debounceTimersRef.current.get(name);
+      if (existingTimer) clearTimeout(existingTimer);
+      const debounceMs = asyncValidator.debounceMs;
+      if (trigger === "change" && debounceMs && debounceMs > 0) {
+        const timer = setTimeout(() => {
+          debounceTimersRef.current.delete(name);
+          runAsyncValidation(name, value);
+        }, debounceMs);
+        debounceTimersRef.current.set(name, timer);
+      } else {
+        runAsyncValidation(name, value);
+      }
+    },
+    [schema, runAsyncValidation]
+  );
+  const validateSingleField = (0, import_react.useCallback)(
+    (name, value, trigger) => {
+      const fieldSchema = schema.fields[name];
+      if (!fieldSchema) return;
+      const formMessages = schema.messages?.[name];
+      const error = (0, import_vorm_core.validateField)(value, fieldSchema, formMessages);
+      if (error) {
+        store.setFieldError(name, error);
+      } else {
+        store.clearFieldError(name);
+      }
+      if (!error && trigger) {
+        scheduleAsyncValidation(name, value, trigger);
+      }
+    },
+    [schema, store, scheduleAsyncValidation]
+  );
+  const setFieldValue = (0, import_react.useCallback)(
+    (name, value) => {
+      store.setFieldValue(name, value);
+      if (mode === "onChange") {
+        validateSingleField(name, value, "change");
+      } else if (mode === "onTouched" && store.getState().touchedFields[name]) {
+        validateSingleField(name, value, "change");
+      }
+    },
+    [mode, store, validateSingleField]
+  );
+  const setFieldTouched = (0, import_react.useCallback)(
+    (name) => {
+      store.setFieldTouched(name);
+      if (mode === "onBlur" || mode === "onTouched") {
+        const currentValue = store.getState().values[name];
+        validateSingleField(name, currentValue, "blur");
+      } else {
+        const currentValue = store.getState().values[name];
+        const fieldSchema = schema.fields[name];
+        if (fieldSchema) {
+          const formMessages = schema.messages?.[name];
+          const syncError = (0, import_vorm_core.validateField)(currentValue, fieldSchema, formMessages);
+          if (!syncError) {
+            scheduleAsyncValidation(name, currentValue, "blur");
+          }
+        }
+      }
+    },
+    [mode, schema, store, validateSingleField, scheduleAsyncValidation]
+  );
+  const setFieldError = (0, import_react.useCallback)(
+    (name, error) => {
+      store.setFieldError(name, error);
+    },
+    [store]
+  );
+  const clearFieldError = (0, import_react.useCallback)(
+    (name) => {
+      store.clearFieldError(name);
+    },
+    [store]
+  );
+  const validate = (0, import_react.useCallback)(
+    (name) => {
+      const currentValues = store.getState().values;
+      if (name) {
+        const fieldSchema = schema.fields[name];
+        if (!fieldSchema) return true;
+        const formMessages = schema.messages?.[name];
+        const error = (0, import_vorm_core.validateField)(
+          currentValues[name],
+          fieldSchema,
+          formMessages
+        );
+        if (error) {
+          store.setFieldError(name, error);
+        } else {
+          store.clearFieldError(name);
+        }
+        return !error;
+      }
+      const formErrors = (0, import_vorm_core.validateForm)(currentValues, schema);
+      store.setErrors(formErrors);
+      return Object.keys(formErrors).length === 0;
+    },
+    [schema, store]
+  );
+  const validateAsync = (0, import_react.useCallback)(
+    async (name) => {
+      const currentValues = store.getState().values;
+      if (name) {
+        const fieldSchema = schema.fields[name];
+        if (!fieldSchema) return true;
+        const formMessages = schema.messages?.[name];
+        const syncError = (0, import_vorm_core.validateField)(
+          currentValues[name],
+          fieldSchema,
+          formMessages
+        );
+        if (syncError) {
+          store.setFieldError(name, syncError);
+        } else {
+          store.clearFieldError(name);
+        }
+        if (syncError) return false;
+        const asyncError = await runAsyncValidation(name, currentValues[name]);
+        return !asyncError;
+      }
+      const formErrors = (0, import_vorm_core.validateForm)(currentValues, schema);
+      store.setErrors(formErrors);
+      if (Object.keys(formErrors).length > 0) return false;
+      const asyncEntries = Object.entries(asyncValidatorsRef.current ?? {});
+      if (asyncEntries.length === 0) return true;
+      const asyncResults = await Promise.all(
+        asyncEntries.map(async ([fieldName]) => {
+          const value = currentValues[fieldName];
+          return runAsyncValidation(fieldName, value);
+        })
+      );
+      return asyncResults.every((error) => error === null);
+    },
+    [schema, store, runAsyncValidation]
+  );
+  const handleSubmit = (0, import_react.useCallback)(
+    (handler) => {
+      return async (e) => {
+        e?.preventDefault?.();
+        const currentValues = store.getState().values;
+        const formErrors = (0, import_vorm_core.validateForm)(currentValues, schema);
+        store.setErrors(formErrors);
+        if (Object.keys(formErrors).length > 0) {
+          return;
+        }
+        const asyncEntries = Object.entries(asyncValidatorsRef.current ?? {});
+        if (asyncEntries.length > 0) {
+          const asyncResults = await Promise.all(
+            asyncEntries.map(async ([fieldName]) => {
+              const value = currentValues[fieldName];
+              const fieldSchema = schema.fields[fieldName];
+              if (fieldSchema) {
+                const formMessages = schema.messages?.[fieldName];
+                const syncError = (0, import_vorm_core.validateField)(value, fieldSchema, formMessages);
+                if (syncError) return null;
+              }
+              return runAsyncValidation(fieldName, value);
+            })
+          );
+          const hasAsyncErrors = asyncResults.some((error) => error !== null);
+          if (hasAsyncErrors) return;
+        }
+        store.setIsSubmitting(true);
+        try {
+          const outputValues = (0, import_vorm_core.buildOutputValues)(
+            currentValues,
+            schema.fields
+          );
+          await handler(outputValues);
+        } finally {
+          store.setIsSubmitting(false);
+        }
+      };
+    },
+    [schema, store, runAsyncValidation]
+  );
+  const reset = (0, import_react.useCallback)(
+    (newValues) => {
+      const resetValues = newValues ? { ...defaultValuesRef.current, ...newValues } : { ...defaultValuesRef.current };
+      store.reset(resetValues);
+      for (const controller of abortControllersRef.current.values()) {
+        controller.abort();
+      }
+      abortControllersRef.current.clear();
+      for (const timer of debounceTimersRef.current.values()) {
+        clearTimeout(timer);
+      }
+      debounceTimersRef.current.clear();
+      validatingFieldsRef.current.clear();
+    },
+    [store]
+  );
+  (0, import_react.useEffect)(() => {
+    return () => {
+      for (const controller of abortControllersRef.current.values()) {
+        controller.abort();
+      }
+      for (const timer of debounceTimersRef.current.values()) {
+        clearTimeout(timer);
+      }
+    };
+  }, []);
+  const field = (name) => {
+    const value = state.values[name];
+    const error = state.errors[name] ?? null;
+    const fieldIsDirty = value !== defaultValuesRef.current[name];
+    const isTouched = state.touchedFields[name] ?? false;
+    const fieldSchema = schema.fields[name];
+    const formatFn = fieldSchema?.format;
+    const parseFn = fieldSchema?.parse;
+    const formattedValue = formatFn ? formatFn(value) : String(value ?? "");
+    return {
+      value,
+      formattedValue,
+      error,
+      isDirty: fieldIsDirty,
+      isTouched,
+      onChange: (raw) => {
+        const parsed = parseFn ? parseFn(raw) : raw;
+        setFieldValue(name, parsed);
+      },
+      onBlur: () => {
+        setFieldTouched(name);
+      }
+    };
+  };
+  return {
+    values: state.values,
+    errors: state.errors,
+    isValid,
+    isDirty: state.isDirty,
+    isSubmitting: state.isSubmitting,
+    isValidating: state.isValidating,
+    touchedFields: state.touchedFields,
+    handleSubmit,
+    reset,
+    setFieldValue,
+    setFieldTouched,
+    setFieldError,
+    clearFieldError,
+    validate,
+    validateAsync,
+    field,
+    schema,
+    mode,
+    defaultValues: defaultValuesRef.current,
+    __store: store
+  };
+}
+
+// src/use-field.ts
+var import_react2 = require("react");
+function useField(form, name) {
+  const store = form.__store;
+  const subscribe = (0, import_react2.useCallback)(
+    (listener) => store.subscribeField(name, listener),
+    [store, name]
+  );
+  const getSnapshot = (0, import_react2.useCallback)(
+    () => store.getFieldSnapshot(name),
+    [store, name]
+  );
+  const snap = (0, import_react2.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+  const value = snap.value;
+  const error = snap.error;
+  const isTouched = snap.isTouched;
+  const isDirty = value !== form.defaultValues[name];
+  const fieldSchema = form.schema.fields[name];
+  const formatFn = fieldSchema?.format;
+  const parseFn = fieldSchema?.parse;
+  const formattedValue = formatFn ? formatFn(value) : String(value ?? "");
+  const onChange = (0, import_react2.useCallback)(
+    (raw) => {
+      const parsed = parseFn ? parseFn(raw) : raw;
+      form.setFieldValue(name, parsed);
+    },
+    [form.setFieldValue, name, parseFn]
+  );
+  const onBlur = (0, import_react2.useCallback)(() => {
+    form.setFieldTouched(name);
+  }, [form.setFieldTouched, name]);
+  return {
+    value,
+    formattedValue,
+    onChange,
+    onBlur,
+    error,
+    isDirty,
+    isTouched
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createFormStore,
+  useField,
+  useForm
+});

package/dist/index.d.cts

@@ -0,0 +1,87 @@
+import { FieldError, FieldSchema, FormInputValues, FormErrors, FormOutputValues, FormSchema } from '@gunubin/vorm-core';
+
+type FieldState<TValue> = {
+    value: TValue;
+    formattedValue: string;
+    onChange: (raw: string) => void;
+    onBlur: () => void;
+    error: FieldError | null;
+    isDirty: boolean;
+    isTouched: boolean;
+};
+declare function useField<TFields extends Record<string, FieldSchema<any, any, boolean, any>>, TName extends string & keyof TFields>(form: FormState<TFields>, name: TName): FieldState<TFields[TName] extends FieldSchema<infer T, any, any, any> ? T : never>;
+
+type FormStoreState<TFields extends Record<string, FieldSchema<any, any, boolean, any>>> = {
+    values: FormInputValues<TFields>;
+    errors: FormErrors;
+    isDirty: boolean;
+    isSubmitting: boolean;
+    isValidating: boolean;
+    touchedFields: Record<string, boolean>;
+};
+type FieldSnapshot = {
+    value: unknown;
+    error: FieldError | null;
+    isTouched: boolean;
+};
+type Listener = () => void;
+type FormStore<TFields extends Record<string, FieldSchema<any, any, boolean, any>>> = {
+    subscribe: (listener: Listener) => () => void;
+    getSnapshot: () => FormStoreState<TFields>;
+    subscribeField: (name: string, listener: Listener) => () => void;
+    getFieldSnapshot: (name: string) => FieldSnapshot;
+    getState: () => FormStoreState<TFields>;
+    setFieldValue: (name: string, value: any) => void;
+    setFieldTouched: (name: string) => void;
+    setFieldError: (name: string, error: FieldError) => void;
+    clearFieldError: (name?: string) => void;
+    setErrors: (errors: FormErrors) => void;
+    setIsSubmitting: (value: boolean) => void;
+    setIsValidating: (value: boolean) => void;
+    reset: (values: FormInputValues<TFields>) => void;
+};
+declare function createFormStore<TFields extends Record<string, FieldSchema<any, any, boolean, any>>>(initialState: FormStoreState<TFields>): FormStore<TFields>;
+
+type ValidationMode = 'onChange' | 'onBlur' | 'onTouched' | 'onSubmit';
+type AsyncTrigger = 'blur' | 'change' | 'submit';
+type AsyncFieldValidator<TInput> = {
+    validate: (value: TInput) => Promise<FieldError | null>;
+    on?: AsyncTrigger;
+    debounceMs?: number;
+};
+type AsyncValidators<TFields extends Record<string, FieldSchema<any, any, boolean, any>>> = {
+    [K in string & keyof TFields]?: AsyncFieldValidator<TFields[K] extends FieldSchema<infer TInput, any, any, any> ? TInput : never>;
+};
+type UseFormOptions<TFields extends Record<string, FieldSchema<any, any, boolean, any>>> = {
+    defaultValues: FormInputValues<TFields>;
+    mode?: ValidationMode;
+    asyncValidators?: AsyncValidators<TFields>;
+};
+type FormState<TFields extends Record<string, FieldSchema<any, any, boolean, any>>> = {
+    values: FormInputValues<TFields>;
+    errors: FormErrors;
+    isValid: boolean;
+    isDirty: boolean;
+    isSubmitting: boolean;
+    isValidating: boolean;
+    touchedFields: Record<string, boolean>;
+    handleSubmit: (handler: (values: FormOutputValues<TFields>) => void | Promise<void>) => (e?: {
+        preventDefault?: () => void;
+    }) => Promise<void>;
+    reset: (values?: Partial<FormInputValues<TFields>>) => void;
+    setFieldValue: (name: string, value: any) => void;
+    setFieldTouched: (name: string) => void;
+    setFieldError: (name: string & keyof TFields, error: FieldError) => void;
+    clearFieldError: (name?: string & keyof TFields) => void;
+    validate: (name?: string & keyof TFields) => boolean;
+    validateAsync: (name?: string & keyof TFields) => Promise<boolean>;
+    field: <TName extends string & keyof TFields>(name: TName) => FieldState<TFields[TName] extends FieldSchema<infer TInput, any, any, any> ? TInput : never>;
+    schema: FormSchema<TFields>;
+    mode: ValidationMode;
+    defaultValues: FormInputValues<TFields>;
+    /** @internal */
+    __store: FormStore<TFields>;
+};
+declare function useForm<TFields extends Record<string, FieldSchema<any, any, boolean, any>>>(schema: FormSchema<TFields>, options: UseFormOptions<TFields>): FormState<TFields>;
+
+export { type AsyncFieldValidator, type AsyncValidators, type FieldSnapshot, type FieldState, type FormState, type FormStore, type FormStoreState, createFormStore, useField, useForm };

package/dist/index.d.ts

@@ -0,0 +1,87 @@
+import { FieldError, FieldSchema, FormInputValues, FormErrors, FormOutputValues, FormSchema } from '@gunubin/vorm-core';
+
+type FieldState<TValue> = {
+    value: TValue;
+    formattedValue: string;
+    onChange: (raw: string) => void;
+    onBlur: () => void;
+    error: FieldError | null;
+    isDirty: boolean;
+    isTouched: boolean;
+};
+declare function useField<TFields extends Record<string, FieldSchema<any, any, boolean, any>>, TName extends string & keyof TFields>(form: FormState<TFields>, name: TName): FieldState<TFields[TName] extends FieldSchema<infer T, any, any, any> ? T : never>;
+
+type FormStoreState<TFields extends Record<string, FieldSchema<any, any, boolean, any>>> = {
+    values: FormInputValues<TFields>;
+    errors: FormErrors;
+    isDirty: boolean;
+    isSubmitting: boolean;
+    isValidating: boolean;
+    touchedFields: Record<string, boolean>;
+};
+type FieldSnapshot = {
+    value: unknown;
+    error: FieldError | null;
+    isTouched: boolean;
+};
+type Listener = () => void;
+type FormStore<TFields extends Record<string, FieldSchema<any, any, boolean, any>>> = {
+    subscribe: (listener: Listener) => () => void;
+    getSnapshot: () => FormStoreState<TFields>;
+    subscribeField: (name: string, listener: Listener) => () => void;
+    getFieldSnapshot: (name: string) => FieldSnapshot;
+    getState: () => FormStoreState<TFields>;
+    setFieldValue: (name: string, value: any) => void;
+    setFieldTouched: (name: string) => void;
+    setFieldError: (name: string, error: FieldError) => void;
+    clearFieldError: (name?: string) => void;
+    setErrors: (errors: FormErrors) => void;
+    setIsSubmitting: (value: boolean) => void;
+    setIsValidating: (value: boolean) => void;
+    reset: (values: FormInputValues<TFields>) => void;
+};
+declare function createFormStore<TFields extends Record<string, FieldSchema<any, any, boolean, any>>>(initialState: FormStoreState<TFields>): FormStore<TFields>;
+
+type ValidationMode = 'onChange' | 'onBlur' | 'onTouched' | 'onSubmit';
+type AsyncTrigger = 'blur' | 'change' | 'submit';
+type AsyncFieldValidator<TInput> = {
+    validate: (value: TInput) => Promise<FieldError | null>;
+    on?: AsyncTrigger;
+    debounceMs?: number;
+};
+type AsyncValidators<TFields extends Record<string, FieldSchema<any, any, boolean, any>>> = {
+    [K in string & keyof TFields]?: AsyncFieldValidator<TFields[K] extends FieldSchema<infer TInput, any, any, any> ? TInput : never>;
+};
+type UseFormOptions<TFields extends Record<string, FieldSchema<any, any, boolean, any>>> = {
+    defaultValues: FormInputValues<TFields>;
+    mode?: ValidationMode;
+    asyncValidators?: AsyncValidators<TFields>;
+};
+type FormState<TFields extends Record<string, FieldSchema<any, any, boolean, any>>> = {
+    values: FormInputValues<TFields>;
+    errors: FormErrors;
+    isValid: boolean;
+    isDirty: boolean;
+    isSubmitting: boolean;
+    isValidating: boolean;
+    touchedFields: Record<string, boolean>;
+    handleSubmit: (handler: (values: FormOutputValues<TFields>) => void | Promise<void>) => (e?: {
+        preventDefault?: () => void;
+    }) => Promise<void>;
+    reset: (values?: Partial<FormInputValues<TFields>>) => void;
+    setFieldValue: (name: string, value: any) => void;
+    setFieldTouched: (name: string) => void;
+    setFieldError: (name: string & keyof TFields, error: FieldError) => void;
+    clearFieldError: (name?: string & keyof TFields) => void;
+    validate: (name?: string & keyof TFields) => boolean;
+    validateAsync: (name?: string & keyof TFields) => Promise<boolean>;
+    field: <TName extends string & keyof TFields>(name: TName) => FieldState<TFields[TName] extends FieldSchema<infer TInput, any, any, any> ? TInput : never>;
+    schema: FormSchema<TFields>;
+    mode: ValidationMode;
+    defaultValues: FormInputValues<TFields>;
+    /** @internal */
+    __store: FormStore<TFields>;
+};
+declare function useForm<TFields extends Record<string, FieldSchema<any, any, boolean, any>>>(schema: FormSchema<TFields>, options: UseFormOptions<TFields>): FormState<TFields>;
+
+export { type AsyncFieldValidator, type AsyncValidators, type FieldSnapshot, type FieldState, type FormState, type FormStore, type FormStoreState, createFormStore, useField, useForm };

package/dist/index.js

@@ -0,0 +1,490 @@
+// src/use-form.ts
+import { useRef, useCallback, useEffect, useSyncExternalStore } from "react";
+import { validateField, validateForm, buildOutputValues } from "@gunubin/vorm-core";
+
+// src/form-store.ts
+function createFormStore(initialState) {
+  let state = initialState;
+  let snapshot = state;
+  const listeners = /* @__PURE__ */ new Set();
+  const fieldListeners = /* @__PURE__ */ new Map();
+  const fieldSnapshotCache = /* @__PURE__ */ new Map();
+  function emit(changedFields) {
+    snapshot = { ...state };
+    for (const listener of listeners) {
+      listener();
+    }
+    if (changedFields) {
+      for (const name of changedFields) {
+        fieldSnapshotCache.delete(name);
+        const set = fieldListeners.get(name);
+        if (set) {
+          for (const listener of set) {
+            listener();
+          }
+        }
+      }
+    } else {
+      fieldSnapshotCache.clear();
+      for (const [, set] of fieldListeners) {
+        for (const listener of set) {
+          listener();
+        }
+      }
+    }
+  }
+  return {
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    getSnapshot() {
+      return snapshot;
+    },
+    subscribeField(name, listener) {
+      if (!fieldListeners.has(name)) {
+        fieldListeners.set(name, /* @__PURE__ */ new Set());
+      }
+      fieldListeners.get(name).add(listener);
+      return () => {
+        fieldListeners.get(name).delete(listener);
+      };
+    },
+    getFieldSnapshot(name) {
+      const cached = fieldSnapshotCache.get(name);
+      if (cached) return cached;
+      const snap = {
+        value: state.values[name],
+        error: state.errors[name] ?? null,
+        isTouched: state.touchedFields[name] ?? false
+      };
+      fieldSnapshotCache.set(name, snap);
+      return snap;
+    },
+    getState() {
+      return state;
+    },
+    setFieldValue(name, value) {
+      state = {
+        ...state,
+        values: { ...state.values, [name]: value },
+        isDirty: true
+      };
+      emit([name]);
+    },
+    setFieldTouched(name) {
+      state = {
+        ...state,
+        touchedFields: { ...state.touchedFields, [name]: true }
+      };
+      emit([name]);
+    },
+    setFieldError(name, error) {
+      state = {
+        ...state,
+        errors: { ...state.errors, [name]: error }
+      };
+      emit([name]);
+    },
+    clearFieldError(name) {
+      if (name) {
+        const next = { ...state.errors };
+        delete next[name];
+        state = { ...state, errors: next };
+        emit([name]);
+      } else {
+        state = { ...state, errors: {} };
+        emit();
+      }
+    },
+    setErrors(errors) {
+      state = { ...state, errors };
+      emit();
+    },
+    setIsSubmitting(value) {
+      state = { ...state, isSubmitting: value };
+      emit();
+    },
+    setIsValidating(value) {
+      state = { ...state, isValidating: value };
+      emit();
+    },
+    reset(values) {
+      state = {
+        values,
+        errors: {},
+        isDirty: false,
+        isSubmitting: false,
+        isValidating: false,
+        touchedFields: {}
+      };
+      emit();
+    }
+  };
+}
+
+// src/use-form.ts
+function useForm(schema, options) {
+  const { defaultValues, mode = "onSubmit", asyncValidators } = options;
+  const storeRef = useRef(null);
+  if (storeRef.current === null) {
+    storeRef.current = createFormStore({
+      values: { ...defaultValues },
+      errors: {},
+      isDirty: false,
+      isSubmitting: false,
+      isValidating: false,
+      touchedFields: {}
+    });
+  }
+  const store = storeRef.current;
+  const state = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
+  const defaultValuesRef = useRef(defaultValues);
+  const asyncValidatorsRef = useRef(asyncValidators);
+  asyncValidatorsRef.current = asyncValidators;
+  const validatingFieldsRef = useRef(/* @__PURE__ */ new Set());
+  const abortControllersRef = useRef(/* @__PURE__ */ new Map());
+  const debounceTimersRef = useRef(/* @__PURE__ */ new Map());
+  const isValid = Object.keys(state.errors).length === 0;
+  const runAsyncValidation = useCallback(
+    async (name, value) => {
+      const asyncValidator = asyncValidatorsRef.current?.[name];
+      if (!asyncValidator) return null;
+      const prevController = abortControllersRef.current.get(name);
+      if (prevController) prevController.abort();
+      const controller = new AbortController();
+      abortControllersRef.current.set(name, controller);
+      validatingFieldsRef.current.add(name);
+      store.setIsValidating(true);
+      try {
+        const error = await asyncValidator.validate(value);
+        if (controller.signal.aborted) return null;
+        if (error) {
+          store.setFieldError(name, error);
+        } else {
+          store.clearFieldError(name);
+        }
+        return error;
+      } finally {
+        if (!controller.signal.aborted) {
+          validatingFieldsRef.current.delete(name);
+          abortControllersRef.current.delete(name);
+          if (validatingFieldsRef.current.size === 0) {
+            store.setIsValidating(false);
+          }
+        }
+      }
+    },
+    [store]
+  );
+  const scheduleAsyncValidation = useCallback(
+    (name, value, trigger) => {
+      const asyncValidator = asyncValidatorsRef.current?.[name];
+      if (!asyncValidator) return;
+      const on = asyncValidator.on ?? "blur";
+      if (on !== trigger) return;
+      const fieldSchema = schema.fields[name];
+      if (fieldSchema) {
+        const formMessages = schema.messages?.[name];
+        const syncError = validateField(value, fieldSchema, formMessages);
+        if (syncError) return;
+      }
+      const existingTimer = debounceTimersRef.current.get(name);
+      if (existingTimer) clearTimeout(existingTimer);
+      const debounceMs = asyncValidator.debounceMs;
+      if (trigger === "change" && debounceMs && debounceMs > 0) {
+        const timer = setTimeout(() => {
+          debounceTimersRef.current.delete(name);
+          runAsyncValidation(name, value);
+        }, debounceMs);
+        debounceTimersRef.current.set(name, timer);
+      } else {
+        runAsyncValidation(name, value);
+      }
+    },
+    [schema, runAsyncValidation]
+  );
+  const validateSingleField = useCallback(
+    (name, value, trigger) => {
+      const fieldSchema = schema.fields[name];
+      if (!fieldSchema) return;
+      const formMessages = schema.messages?.[name];
+      const error = validateField(value, fieldSchema, formMessages);
+      if (error) {
+        store.setFieldError(name, error);
+      } else {
+        store.clearFieldError(name);
+      }
+      if (!error && trigger) {
+        scheduleAsyncValidation(name, value, trigger);
+      }
+    },
+    [schema, store, scheduleAsyncValidation]
+  );
+  const setFieldValue = useCallback(
+    (name, value) => {
+      store.setFieldValue(name, value);
+      if (mode === "onChange") {
+        validateSingleField(name, value, "change");
+      } else if (mode === "onTouched" && store.getState().touchedFields[name]) {
+        validateSingleField(name, value, "change");
+      }
+    },
+    [mode, store, validateSingleField]
+  );
+  const setFieldTouched = useCallback(
+    (name) => {
+      store.setFieldTouched(name);
+      if (mode === "onBlur" || mode === "onTouched") {
+        const currentValue = store.getState().values[name];
+        validateSingleField(name, currentValue, "blur");
+      } else {
+        const currentValue = store.getState().values[name];
+        const fieldSchema = schema.fields[name];
+        if (fieldSchema) {
+          const formMessages = schema.messages?.[name];
+          const syncError = validateField(currentValue, fieldSchema, formMessages);
+          if (!syncError) {
+            scheduleAsyncValidation(name, currentValue, "blur");
+          }
+        }
+      }
+    },
+    [mode, schema, store, validateSingleField, scheduleAsyncValidation]
+  );
+  const setFieldError = useCallback(
+    (name, error) => {
+      store.setFieldError(name, error);
+    },
+    [store]
+  );
+  const clearFieldError = useCallback(
+    (name) => {
+      store.clearFieldError(name);
+    },
+    [store]
+  );
+  const validate = useCallback(
+    (name) => {
+      const currentValues = store.getState().values;
+      if (name) {
+        const fieldSchema = schema.fields[name];
+        if (!fieldSchema) return true;
+        const formMessages = schema.messages?.[name];
+        const error = validateField(
+          currentValues[name],
+          fieldSchema,
+          formMessages
+        );
+        if (error) {
+          store.setFieldError(name, error);
+        } else {
+          store.clearFieldError(name);
+        }
+        return !error;
+      }
+      const formErrors = validateForm(currentValues, schema);
+      store.setErrors(formErrors);
+      return Object.keys(formErrors).length === 0;
+    },
+    [schema, store]
+  );
+  const validateAsync = useCallback(
+    async (name) => {
+      const currentValues = store.getState().values;
+      if (name) {
+        const fieldSchema = schema.fields[name];
+        if (!fieldSchema) return true;
+        const formMessages = schema.messages?.[name];
+        const syncError = validateField(
+          currentValues[name],
+          fieldSchema,
+          formMessages
+        );
+        if (syncError) {
+          store.setFieldError(name, syncError);
+        } else {
+          store.clearFieldError(name);
+        }
+        if (syncError) return false;
+        const asyncError = await runAsyncValidation(name, currentValues[name]);
+        return !asyncError;
+      }
+      const formErrors = validateForm(currentValues, schema);
+      store.setErrors(formErrors);
+      if (Object.keys(formErrors).length > 0) return false;
+      const asyncEntries = Object.entries(asyncValidatorsRef.current ?? {});
+      if (asyncEntries.length === 0) return true;
+      const asyncResults = await Promise.all(
+        asyncEntries.map(async ([fieldName]) => {
+          const value = currentValues[fieldName];
+          return runAsyncValidation(fieldName, value);
+        })
+      );
+      return asyncResults.every((error) => error === null);
+    },
+    [schema, store, runAsyncValidation]
+  );
+  const handleSubmit = useCallback(
+    (handler) => {
+      return async (e) => {
+        e?.preventDefault?.();
+        const currentValues = store.getState().values;
+        const formErrors = validateForm(currentValues, schema);
+        store.setErrors(formErrors);
+        if (Object.keys(formErrors).length > 0) {
+          return;
+        }
+        const asyncEntries = Object.entries(asyncValidatorsRef.current ?? {});
+        if (asyncEntries.length > 0) {
+          const asyncResults = await Promise.all(
+            asyncEntries.map(async ([fieldName]) => {
+              const value = currentValues[fieldName];
+              const fieldSchema = schema.fields[fieldName];
+              if (fieldSchema) {
+                const formMessages = schema.messages?.[fieldName];
+                const syncError = validateField(value, fieldSchema, formMessages);
+                if (syncError) return null;
+              }
+              return runAsyncValidation(fieldName, value);
+            })
+          );
+          const hasAsyncErrors = asyncResults.some((error) => error !== null);
+          if (hasAsyncErrors) return;
+        }
+        store.setIsSubmitting(true);
+        try {
+          const outputValues = buildOutputValues(
+            currentValues,
+            schema.fields
+          );
+          await handler(outputValues);
+        } finally {
+          store.setIsSubmitting(false);
+        }
+      };
+    },
+    [schema, store, runAsyncValidation]
+  );
+  const reset = useCallback(
+    (newValues) => {
+      const resetValues = newValues ? { ...defaultValuesRef.current, ...newValues } : { ...defaultValuesRef.current };
+      store.reset(resetValues);
+      for (const controller of abortControllersRef.current.values()) {
+        controller.abort();
+      }
+      abortControllersRef.current.clear();
+      for (const timer of debounceTimersRef.current.values()) {
+        clearTimeout(timer);
+      }
+      debounceTimersRef.current.clear();
+      validatingFieldsRef.current.clear();
+    },
+    [store]
+  );
+  useEffect(() => {
+    return () => {
+      for (const controller of abortControllersRef.current.values()) {
+        controller.abort();
+      }
+      for (const timer of debounceTimersRef.current.values()) {
+        clearTimeout(timer);
+      }
+    };
+  }, []);
+  const field = (name) => {
+    const value = state.values[name];
+    const error = state.errors[name] ?? null;
+    const fieldIsDirty = value !== defaultValuesRef.current[name];
+    const isTouched = state.touchedFields[name] ?? false;
+    const fieldSchema = schema.fields[name];
+    const formatFn = fieldSchema?.format;
+    const parseFn = fieldSchema?.parse;
+    const formattedValue = formatFn ? formatFn(value) : String(value ?? "");
+    return {
+      value,
+      formattedValue,
+      error,
+      isDirty: fieldIsDirty,
+      isTouched,
+      onChange: (raw) => {
+        const parsed = parseFn ? parseFn(raw) : raw;
+        setFieldValue(name, parsed);
+      },
+      onBlur: () => {
+        setFieldTouched(name);
+      }
+    };
+  };
+  return {
+    values: state.values,
+    errors: state.errors,
+    isValid,
+    isDirty: state.isDirty,
+    isSubmitting: state.isSubmitting,
+    isValidating: state.isValidating,
+    touchedFields: state.touchedFields,
+    handleSubmit,
+    reset,
+    setFieldValue,
+    setFieldTouched,
+    setFieldError,
+    clearFieldError,
+    validate,
+    validateAsync,
+    field,
+    schema,
+    mode,
+    defaultValues: defaultValuesRef.current,
+    __store: store
+  };
+}
+
+// src/use-field.ts
+import { useCallback as useCallback2, useSyncExternalStore as useSyncExternalStore2 } from "react";
+function useField(form, name) {
+  const store = form.__store;
+  const subscribe = useCallback2(
+    (listener) => store.subscribeField(name, listener),
+    [store, name]
+  );
+  const getSnapshot = useCallback2(
+    () => store.getFieldSnapshot(name),
+    [store, name]
+  );
+  const snap = useSyncExternalStore2(subscribe, getSnapshot, getSnapshot);
+  const value = snap.value;
+  const error = snap.error;
+  const isTouched = snap.isTouched;
+  const isDirty = value !== form.defaultValues[name];
+  const fieldSchema = form.schema.fields[name];
+  const formatFn = fieldSchema?.format;
+  const parseFn = fieldSchema?.parse;
+  const formattedValue = formatFn ? formatFn(value) : String(value ?? "");
+  const onChange = useCallback2(
+    (raw) => {
+      const parsed = parseFn ? parseFn(raw) : raw;
+      form.setFieldValue(name, parsed);
+    },
+    [form.setFieldValue, name, parseFn]
+  );
+  const onBlur = useCallback2(() => {
+    form.setFieldTouched(name);
+  }, [form.setFieldTouched, name]);
+  return {
+    value,
+    formattedValue,
+    onChange,
+    onBlur,
+    error,
+    isDirty,
+    isTouched
+  };
+}
+export {
+  createFormStore,
+  useField,
+  useForm
+};

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@gunubin/vorm-react",
+  "version": "0.1.0",
+  "description": "VO-first React form hooks with per-field subscriptions via useSyncExternalStore",
+  "keywords": [
+    "form",
+    "react",
+    "hooks",
+    "validation",
+    "branded-types",
+    "typescript"
+  ],
+  "license": "MIT",
+  "author": "gunubin",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gunubin/vorm.git",
+    "directory": "packages/react"
+  },
+  "homepage": "https://github.com/gunubin/vorm#readme",
+  "bugs": {
+    "url": "https://github.com/gunubin/vorm/issues"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "dependencies": {
+    "@gunubin/vorm-core": "0.1.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.0",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "jsdom": "^26.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.0.5"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}