ctrovalidate-react 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ctrotech
+
+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,98 @@
+# ctrovalidate-react
+
+**Headless form validation hook for React.**
+
+`ctrovalidate-react` provides `useCtrovalidate`, a single hook that wraps [`ctrovalidate-core`](https://www.npmjs.com/package/ctrovalidate-core)'s validation engine with reactive state, stable callbacks, and automatic abort handling for async rules.
+
+[![npm version](https://img.shields.io/npm/v/ctrovalidate-react.svg)](https://www.npmjs.com/package/ctrovalidate-react)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Installation
+
+```bash
+npm install ctrovalidate-react ctrovalidate-core
+```
+
+**Requirements:** React >=16.8.0
+
+---
+
+## Quick Start
+
+```tsx
+import { useCtrovalidate } from 'ctrovalidate-react';
+
+interface LoginForm { email: string; password: string; }
+
+function LoginPage() {
+  const { values, errors, handleChange, handleBlur, validateForm, isValidating } =
+    useCtrovalidate<LoginForm>({
+      initialValues: { email: '', password: '' },
+      schema: { email: 'required|email', password: 'required|minLength:8' },
+    });
+
+  return (
+    <form onSubmit={async (e) => { e.preventDefault(); if (await validateForm()) { /* submit */ } }}>
+      <input value={values.email} onChange={(e) => handleChange('email', e.target.value)} onBlur={() => handleBlur('email')} />
+      {errors.email && <span>{errors.email}</span>}
+
+      <input type="password" value={values.password} onChange={(e) => handleChange('password', e.target.value)} onBlur={() => handleBlur('password')} />
+      {errors.password && <span>{errors.password}</span>}
+
+      <button type="submit" disabled={Object.values(isValidating).some(Boolean)}>Login</button>
+    </form>
+  );
+}
+```
+
+---
+
+## API
+
+```typescript
+const {
+  values,         // Current form state
+  errors,         // Partial<Record<keyof T, string>> — undefined if valid
+  isDirty,        // Tracks touched fields
+  isValidating,   // Tracks async validation in progress
+  handleChange,   // Updates value, marks dirty, validates
+  handleBlur,     // Marks dirty, validates (unless validateOnBlur: false)
+  validateField,  // Validate a single field
+  validateForm,   // Validate all fields
+  reset,          // Reset to initial values, clear errors
+} = useCtrovalidate<T>({
+  schema,            // Required: field-to-rules mapping
+  initialValues,     // Optional: form defaults (default: {})
+  validateOnBlur,    // Optional: validate on blur (default: true)
+  customRules,       // Optional: custom sync/async rule functions
+  aliases,           // Optional: rule combination aliases
+  messages,          // Optional: custom error messages
+  locale,            // Optional: locale override for translator
+});
+```
+
+---
+
+## Abort Handling
+
+Each field has its own `AbortController`. Re-validating a field aborts any in-flight async rule. All controllers are aborted on unmount — no stale state updates.
+
+---
+
+## Related Packages
+
+- **[ctrovalidate-core](https://www.npmjs.com/package/ctrovalidate-core)** — Validation engine
+- **[ctrovalidate-browser](https://www.npmjs.com/package/ctrovalidate-browser)** — Vanilla JS DOM integration
+- **[ctrovalidate-vue](https://www.npmjs.com/package/ctrovalidate-vue)** — Vue composable
+- **[ctrovalidate-svelte](https://www.npmjs.com/package/ctrovalidate-svelte)** — Svelte stores
+- **[ctrovalidate-next](https://www.npmjs.com/package/ctrovalidate-next)** — Next.js server actions
+
+---
+
+## License
+
+MIT © [Ctrotech](https://github.com/ctrotech-tutor)
+
+Full documentation: https://ctrovalidate.vercel.app

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const t=require("react"),h=require("ctrovalidate-core");function q(v){const{initialValues:V={}}=v,[l,R]=t.useState(V),[E,b]=t.useState({}),[S,g]=t.useState({}),[k,y]=t.useState({}),o=t.useRef(v);t.useEffect(()=>{o.current=v});const C=t.useRef(l);C.current=l;const n=t.useRef({});t.useEffect(()=>()=>{Object.values(n.current).forEach(e=>e.abort())},[]);const u=t.useCallback(async(e,s)=>{var f;const r=e,a=o.current,i=a.schema[r];if(!i)return!0;const d=s!==void 0?s:C.current[e];n.current[r]&&n.current[r].abort(),n.current[r]=new AbortController,y(c=>({...c,[e]:!0}));try{const m=(f=(await h.validateAsync({[r]:d},{[r]:i},{customRules:a.customRules,aliases:a.aliases,messages:a.messages,locale:a.locale,signal:n.current[r].signal}))[r])==null?void 0:f.error;return b(p=>({...p,[e]:m||void 0})),!m}catch(c){return c instanceof Error&&c.name==="AbortError"||h.Logger.error(`Validation failed for ${r}:`,c),!1}finally{y(c=>({...c,[e]:!1}))}},[]),O=t.useCallback((e,s)=>{R(r=>({...r,[e]:s})),g(r=>({...r,[e]:!0})),u(e,s)},[u]),w=t.useCallback(e=>{g(s=>({...s,[e]:!0})),o.current.validateOnBlur!==!1&&u(e,C.current[e])},[u]),A=t.useCallback(async()=>{var i;const e=o.current,s=await h.validateAsync(l,e.schema,{customRules:e.customRules,aliases:e.aliases,messages:e.messages,locale:e.locale}),r={};let a=!0;for(const d in e.schema){const f=(i=s[d])==null?void 0:i.error;r[d]=f||void 0,f&&(a=!1)}return b(r),a},[l]),j=t.useCallback(e=>{R(e||o.current.initialValues||{}),b({}),g({}),y({})},[]);return{values:l,errors:E,isDirty:S,isValidating:k,handleChange:O,handleBlur:w,validateField:u,validateForm:A,reset:j}}exports.useCtrovalidate=q;

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+import { AsyncRuleLogic } from 'ctrovalidate-core';
+import { RuleLogic } from 'ctrovalidate-core';
+import { SchemaRule } from 'ctrovalidate-core';
+import { ValidationSchema } from 'ctrovalidate-core';
+
+/**
+ * useCtrovalidate hook for React.
+ * Headless validation logic designed for controlled inputs.
+ */
+export declare function useCtrovalidate<T extends object = object>(options: UseCtrovalidateOptions<T>): UseCtrovalidateReturn<T>;
+
+export declare interface UseCtrovalidateOptions<T extends object> {
+    schema: ValidationSchema;
+    initialValues?: T;
+    validateOnBlur?: boolean;
+    customRules?: Record<string, RuleLogic | AsyncRuleLogic>;
+    aliases?: Record<string, SchemaRule>;
+    messages?: Record<string, string>;
+    locale?: string;
+}
+
+export declare interface UseCtrovalidateReturn<T extends object> {
+    values: T;
+    errors: Partial<Record<keyof T, string>>;
+    isDirty: Partial<Record<keyof T, boolean>>;
+    isValidating: Partial<Record<keyof T, boolean>>;
+    handleChange: (name: keyof T, value: T[keyof T]) => void;
+    handleBlur: (name: keyof T) => void;
+    validateField: (name: keyof T, value?: T[keyof T]) => Promise<boolean>;
+    validateForm: () => Promise<boolean>;
+    reset: (newValues?: Partial<T>) => void;
+}
+
+export { }

package/dist/index.js

@@ -0,0 +1,85 @@
+import { useState as g, useRef as b, useEffect as C, useCallback as f } from "react";
+import { validateAsync as p, Logger as j } from "ctrovalidate-core";
+function N(m) {
+  const { initialValues: w = {} } = m, [a, R] = g(w), [O, v] = g({}), [A, h] = g({}), [k, y] = g({}), n = b(m);
+  C(() => {
+    n.current = m;
+  });
+  const V = b(a);
+  V.current = a;
+  const c = b({});
+  C(() => () => {
+    Object.values(c.current).forEach((r) => r.abort());
+  }, []);
+  const l = f(
+    async (r, t) => {
+      var u;
+      const e = r, s = n.current, i = s.schema[e];
+      if (!i) return !0;
+      const d = t !== void 0 ? t : V.current[r];
+      c.current[e] && c.current[e].abort(), c.current[e] = new AbortController(), y((o) => ({ ...o, [r]: !0 }));
+      try {
+        const E = (u = (await p(
+          { [e]: d },
+          { [e]: i },
+          {
+            customRules: s.customRules,
+            aliases: s.aliases,
+            messages: s.messages,
+            locale: s.locale,
+            signal: c.current[e].signal
+          }
+        ))[e]) == null ? void 0 : u.error;
+        return v((S) => ({ ...S, [r]: E || void 0 })), !E;
+      } catch (o) {
+        return o instanceof Error && o.name === "AbortError" || j.error(`Validation failed for ${e}:`, o), !1;
+      } finally {
+        y((o) => ({ ...o, [r]: !1 }));
+      }
+    },
+    []
+    // No dependencies because we use optionsRef
+  ), B = f(
+    (r, t) => {
+      R((e) => ({ ...e, [r]: t })), h((e) => ({ ...e, [r]: !0 })), l(r, t);
+    },
+    [l]
+  ), D = f(
+    (r) => {
+      h((t) => ({ ...t, [r]: !0 })), n.current.validateOnBlur !== !1 && l(r, V.current[r]);
+    },
+    [l]
+  ), F = f(async () => {
+    var i;
+    const r = n.current, t = await p(a, r.schema, {
+      customRules: r.customRules,
+      aliases: r.aliases,
+      messages: r.messages,
+      locale: r.locale
+    }), e = {};
+    let s = !0;
+    for (const d in r.schema) {
+      const u = (i = t[d]) == null ? void 0 : i.error;
+      e[d] = u || void 0, u && (s = !1);
+    }
+    return v(e), s;
+  }, [a]), I = f((r) => {
+    R(
+      r || n.current.initialValues || {}
+    ), v({}), h({}), y({});
+  }, []);
+  return {
+    values: a,
+    errors: O,
+    isDirty: A,
+    isValidating: k,
+    handleChange: B,
+    handleBlur: D,
+    validateField: l,
+    validateForm: F,
+    reset: I
+  };
+}
+export {
+  N as useCtrovalidate
+};

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "ctrovalidate-react",
+  "version": "1.0.0",
+  "description": "React adapter for Ctrovalidate.",
+  "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"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite build --watch",
+    "lint": "eslint .",
+    "test": "vitest run --passWithNoTests"
+  },
+  "homepage": "https://ctrovalidate.vercel.app/api/react",
+  "keywords": [
+    "ctrovalidate",
+    "validation",
+    "form-validation",
+    "react",
+    "hooks"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ctrotech-tutor/ctrovalidate-react.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ctrotech-tutor/ctrovalidate-react/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "ctrovalidate-core": "^1.0.0",
+    "react": ">=16.8.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@types/react": "^18.2.0",
+    "ctrovalidate-core": "^1.0.0",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^9.1.0",
+    "globals": "^17.2.0",
+    "prettier": "^3.1.1",
+    "react": "^18.2.0",
+    "vite": "^6.0.0",
+    "vite-plugin-dts": "^4.0.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.54.0",
+    "vitest": "^4.0.18"
+  }
+}