react-form-manage 1.0.6-beta.2 → 1.0.6-beta.4

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.0.6-beta.4] - 2026-01-22
+
+- Update README with validation rule examples (pattern, async validator)
+- Remove Vite template boilerplate from docs
+
+## [1.0.6-beta.3] - 2026-01-22
+
+- Add `ValidationRule` typing and export
+- Support custom regex `pattern` in validation
+- Update usage docs with numeric-only example
+- Add demo field `numericCode` using pattern rule
+
 ## [1.0.6-beta.2] - 2026-01-22
 
 - Fix TypeScript prop types for all components

package/README.md

@@ -72,6 +72,8 @@ export default Example;
 
 `Form` sẽ đăng ký form instance trong store nội bộ và inject `value` / `onChange` vào các children của `FormItem`.
 
+`ValidationRule` là type public được export để bạn mô tả rules rõ ràng trong TypeScript.
+
 ---
 
 ## Form API / Programmatic usage
@@ -108,6 +110,48 @@ Methods available on the form instance (populated by `Form` provider):
 
 ---
 
+## Validation rules
+
+Hỗ trợ các rule phổ biến: `required`, `min`, `max`, `len`, `pattern`, `enum`, `whitespace`, `type` và custom `validator`. `pattern` nhận `RegExp`; `validator` nhận hàm sync/async `(value, ctx) => void | Promise<void>`.
+
+Ví dụ pattern + required:
+
+```tsx
+<Form formName="codeForm" initialValues={{ numericCode: "" }}>
+  <FormItem
+    name="numericCode"
+    rules={[
+      { required: true, message: "Code is required" },
+      { pattern: /^\d+$/, message: "Only digits are allowed" },
+    ]}
+  >
+    <Input placeholder="Enter digits only" />
+  </FormItem>
+  <button type="submit">Submit</button>
+</Form>
+```
+
+Custom validator (async):
+
+```tsx
+<FormItem
+  name="username"
+  rules={[
+    {
+      validator: async (value) => {
+        if (!value) throw new Error("Username required");
+        const exists = await api.checkUser(value);
+        if (exists) throw new Error("Username already taken");
+      },
+    },
+  ]}
+>
+  <Input placeholder="Username" />
+</FormItem>
+```
+
+---
+
 ## FormList (Array field)
 
 `FormList` là render-prop component cung cấp `listFields` và các action `add`, `remove`, `move`.
@@ -186,20 +230,3 @@ Nếu bạn muốn tự sinh `.d.ts` từ JS, có thể thêm `tsconfig.types.js
 ## License
 
 Mặc định chưa thêm license — nếu muốn public, hãy thêm `LICENSE` (ví dụ MIT).
-
-# React + Vite
-
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
-
-Currently, two official plugins are available:
-
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
-
-## React Compiler
-
-The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
-
-## Expanding the ESLint configuration
-
-If you are developing a production application, we recommend using TypeScript with type-aware lint rules enabled. Check out the [TS template](https://github.com/vitejs/vite/tree/main/packages/create-vite/template-react-ts) for information on how to integrate TypeScript and [`typescript-eslint`](https://typescript-eslint.io) in your project.

package/dist/components/Form/FormItem.d.ts

@@ -1,11 +1,12 @@
 import type { ReactElement } from "react";
+import type { ValidationRule } from "../../types/public";
 export interface FormItemProps {
     children: ReactElement;
     name: string;
     formName?: string;
     initialValue?: any;
     formItemId?: string;
-    rules?: any[];
+    rules?: ValidationRule[];
     valuePropName?: string;
     getValueFromEvent?: (event: any) => any;
 }

package/dist/hooks/useFormItemControl.d.ts

@@ -1,5 +1,6 @@
 import { type RefObject } from "react";
 import type { FormInstance } from "../stores/formStore";
+import type { ValidationRule } from "../types/public";
 type AnyObject = Record<string, any>;
 interface UseFormItemControlProps {
     formName?: string;
@@ -7,7 +8,7 @@ interface UseFormItemControlProps {
     name?: string;
     initialValue?: any;
     formItemId?: string;
-    rules?: any[];
+    rules?: ValidationRule[];
     elementRef?: RefObject<any> | null;
 }
 interface UseFormItemControlReturn {

package/dist/hooks/useFormItemControl.js

@@ -8,12 +8,14 @@ import { useFormCleanUp, useFormListeners, useFormStore, } from "../stores/formS
 const VALID_PREMITIVE_TYPE = ["string", "number", "undefined"];
 export default function useFormItemControl({ formName, form, name, initialValue, formItemId, rules, elementRef, }) {
     const contextForm = useFormContext();
-    const { value, setData, getCacheData, getFormValues } = useFormStore(useShallow((state) => {
+    const { value, setData, getCacheData, getFormValues, getFormState, isStateInitied, } = useFormStore(useShallow((state) => {
         return {
             value: get(state.forms, `${formName || form?.formName || contextForm?.formName}.${name}`),
             setData: state.setData,
             getCacheData: state.getCacheData,
             getFormValues: state.getFormValues,
+            getFormState: state.getFormState,
+            isStateInitied: state.formStates?.[formName || form?.formName || contextForm?.formName]?.isInitied,
         };
     }));
     const { setCleanUpStack } = useFormCleanUp(useShallow((state) => ({
@@ -53,6 +55,7 @@ export default function useFormItemControl({ formName, form, name, initialValue,
         //   value
         // );
         setInitData(formName || form?.formName || contextForm?.formName, name, value);
+        onChange(value, { notTriggerDirty: true });
     };
     const onFocus = () => {
         setListener({
@@ -171,6 +174,14 @@ export default function useFormItemControl({ formName, form, name, initialValue,
                             }
                         }
                     }
+                    // Custom pattern
+                    if (r.pattern && !r.pattern.test(fieldValue || "")) {
+                        listErrors.push({
+                            ruleName,
+                            message: r.message,
+                        });
+                        return;
+                    }
                     // Password
                     if (r.isPassword && !IS_PASSWORD_REGEX.test(fieldValue)) {
                         // tempMessage.push(IS_PASSWORD_INVALID_MESSAGE);
@@ -319,18 +330,22 @@ export default function useFormItemControl({ formName, form, name, initialValue,
         // console.log({ internalInitValue, value, initialValue });
         // console.log("Init item value: ", name, value, internalInitValue);
         // console.log("internalInitValue: ", internalInitValue);
-        if (!value) {
-            if (!internalInitValue) {
-                if (!isNil(initialValue)) {
-                    console.log("On init data", initialValue);
-                    onInitData(initialValue);
+        if (isStateInitied) {
+            // console.log("Skip set init data when form is resetting");
+            if (isNil(value)) {
+                if (isNil(internalInitValue)) {
+                    if (isNil(initialValue)) {
+                        console.log("On init data", initialValue);
+                        onInitData(initialValue);
+                    }
+                }
+                else {
+                    onChange(internalInitValue, { notTriggerDirty: true });
                 }
             }
-            else {
-                onChange(internalInitValue);
-            }
+            return;
         }
-    }, [internalInitValue]);
+    }, [isStateInitied]);
     useEffect(() => {
         if (!listener) {
             setListener({

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-import Form, { useForm, useWatch, useSubmitDataWatch, useFormStateWatch, type FormProps } from "./providers/Form";
+import Form, { useForm, useWatch, useSubmitDataWatch, useFormStateWatch, type FormProps, type ValidationRule } from "./providers/Form";
 import FormItem, { type FormItemProps } from "./components/Form/FormItem";
 import FormList, { type FormListProps } from "./components/Form/FormList";
 import Input from "./components/Input";
 import InputWrapper, { type InputWrapperProps } from "./components/Form/InputWrapper";
 import useFormItemControl from "./hooks/useFormItemControl";
 import useFormListControl from "./hooks/useFormListControl";
-export { Form, FormItem, FormList, Input, InputWrapper, useFormItemControl, useFormListControl, useForm, useWatch, useSubmitDataWatch, useFormStateWatch, type FormProps, type FormItemProps, type FormListProps, type InputWrapperProps, };
+export { Form, FormItem, FormList, Input, InputWrapper, useFormItemControl, useFormListControl, useForm, useWatch, useSubmitDataWatch, useFormStateWatch, type FormProps, type FormItemProps, type FormListProps, type InputWrapperProps, type ValidationRule, };
 export default Form;

package/dist/providers/Form.d.ts

@@ -1,7 +1,8 @@
-import type { ReactNode, ComponentType, FormHTMLAttributes } from "react";
+import type { ComponentType, FormHTMLAttributes, ReactNode } from "react";
 import type { PublicFormInstance } from "../types/public";
+export type { ValidationRule } from "../types/public";
 export declare const FormContext: import("react").Context<any>;
-export interface FormProps<T = any> extends Omit<FormHTMLAttributes<HTMLFormElement>, 'onSubmit'> {
+export interface FormProps<T = any> extends Omit<FormHTMLAttributes<HTMLFormElement>, "onSubmit"> {
     children: ReactNode;
     formName: string;
     initialValues?: T;

package/dist/providers/Form.js

@@ -9,8 +9,9 @@ import { useFormListeners, useFormStore } from "../stores/formStore";
 import { getAllNoneObjStringPath } from "../utils/obj.util";
 export const FormContext = createContext(null);
 export default function Form({ children, formName, initialValues, onFinish, onReject, onFinally, FormElement, ...props }) {
-    const { getFormItemValue, setInitData, setData, getFormValues, setFormState, setFormInstance, revokeFormInstance, setSubmitHistory, clearFormValues, clearFormInitialValues, clearFormState, } = useFormStore(useShallow((state) => ({
-        setInitData: state.setFormInitData,
+    const { appInitValue, getFormItemValue, setInitData, setData, getFormValues, setFormState, setFormInstance, revokeFormInstance, setSubmitHistory, clearFormValues, clearFormInitialValues, clearFormState, } = useFormStore(useShallow((state) => ({
+        appInitValue: state.initialValues,
+        setInitData: state.setInitData,
         getFormValues: state.getFormValues,
         setFormState: state.setFormState,
         setFormInstance: state.setFormInstance,
@@ -237,7 +238,19 @@ export default function Form({ children, formName, initialValues, onFinish, onRe
         });
     };
     useEffect(() => {
-        setInitData(formName, initialValues);
+        // set initial values
+        if (initialValues) {
+            const allStringPath = getAllNoneObjStringPath(initialValues);
+            allStringPath.forEach((p) => {
+                // console.log(
+                //   "Set initial value for form",
+                //   formName,
+                //   p,
+                //   get(initialValues, p),
+                // );
+                setInitData(formName, p, get(initialValues, p));
+            });
+        }
         setFormState({
             formName,
             isInitied: true,
@@ -262,6 +275,9 @@ export default function Form({ children, formName, initialValues, onFinish, onRe
             clearFormState(formName);
         };
     }, []);
+    // useEffect(() => {
+    //   // console.log("Form appInitValue changed", appInitValue);
+    // }, [appInitValue]);
     return (_jsxs(FormContext.Provider, { value: {
             formName,
         }, children: [FormElement ? (_jsx(FormElement, { onSubmit: (e) => {
@@ -281,7 +297,8 @@ export function useFormContext() {
     return c;
 }
 export function useForm(formNameOrFormInstance) {
-    const targetFormName = typeof formNameOrFormInstance === "object" && formNameOrFormInstance !== null
+    const targetFormName = typeof formNameOrFormInstance === "object" &&
+        formNameOrFormInstance !== null
         ? formNameOrFormInstance.formName
         : formNameOrFormInstance;
     const formInstance = useFormStore((state) => {

package/dist/stores/formStore.d.ts

@@ -1,14 +1,17 @@
 export interface FormInstance {
     formName: string;
-    resetFields?: any;
-    submit?: any;
-    submitAsync?: any;
-    setFieldValue?: any;
-    setFieldValues?: any;
-    getFieldValue?: any;
-    getFieldValues?: any;
-    getFieldErrors?: any;
-    setFieldFocus?: any;
+    resetFields: (values?: any) => void;
+    submit: (values?: any) => void;
+    submitAsync: (values?: any) => Promise<any>;
+    setFieldValue: (name: string, value: any, options?: any) => void;
+    setFieldValues: (values: Record<string, any>, options?: any) => void;
+    getFieldValue: (name: string) => any;
+    getFieldValues: (names?: string[]) => Array<{
+        name: string;
+        value: any;
+    }>;
+    getFieldErrors: () => Record<string, any>;
+    setFieldFocus: (name: string) => void;
 }
 interface FormStoreState {
     forms: Record<string, any>;

package/dist/stores/formStore.js

@@ -126,7 +126,7 @@ export const useFormStore = create((storeSet, storeGet) => ({
     setInitData(formName, name, value) {
         return storeSet(produce((state) => {
             const oldValues = state.initialValues;
-            // console.log("Inner init: ", `${formName}.${name}`, value);
+            console.log("Inner init: ", `${formName}.${name}`, value);
             set(oldValues, `${formName}.${name}`, value);
         }));
     },

package/dist/types/public.d.ts

@@ -1,14 +1,42 @@
 export type FormValues<T = any> = T;
+export interface ValidationRule<T = any, TValues = any> {
+    name?: string;
+    message: string;
+    handler?: (value: T, formValues: TValues) => boolean | Promise<boolean>;
+    required?: boolean;
+    min?: number;
+    max?: number;
+    minLength?: number;
+    maxLength?: number;
+    isPassword?: boolean;
+    isUsername?: boolean;
+    isPhoneNumber?: boolean;
+    isStringNumber?: boolean;
+    isPositiveStringNumber?: boolean;
+    isPositiveIntegerStringNumber?: boolean;
+    isEmail?: boolean;
+    isVietnameseName?: boolean;
+    isNoSpaceStringAndNumber?: boolean;
+    isStringAndNumber?: boolean;
+    isNoSpaceOnlyAlphabetStringAndNumber?: boolean;
+    isOnlyAlphabetStringAndNumber?: boolean;
+    isNoSpaceAlphabetString?: boolean;
+    pattern?: RegExp;
+}
 export interface PublicFormInstance<T = any> {
     formName: string;
-    resetFields?: (values?: Partial<T>) => void;
-    submit?: (values?: T) => void;
-    submitAsync?: (values?: T) => Promise<any>;
-    setFieldValue?: (name: keyof T & string, value: any) => void;
-    setFieldValues?: (values: Partial<T>) => void;
-    getFieldValue?: (name: keyof T & string) => any;
-    getFieldValues?: () => T;
-    getFieldErrors?: () => Record<string, any>;
+    resetFields: (values?: Partial<T>) => void;
+    submit: (values?: T) => void;
+    submitAsync: (values?: T) => Promise<any>;
+    setFieldValue: (name: keyof T & string, value: any, options?: any) => void;
+    setFieldValues: (values: Partial<T>, options?: any) => void;
+    getFieldValue: (name: keyof T & string) => any;
+    getFieldValues: (names?: Array<keyof T & string>) => Array<{
+        name: string;
+        value: any;
+    }>;
+    getFieldErrors: () => Record<string, any>;
+    setFieldFocus: (name: keyof T & string) => void;
 }
 export interface UseFormItemProps<T = any> {
     formName?: string;
@@ -16,7 +44,7 @@ export interface UseFormItemProps<T = any> {
     name?: keyof T & string;
     initialValue?: any;
     formItemId?: string;
-    rules?: any[];
+    rules?: ValidationRule<any, T>[];
 }
 export interface UseFormItemReturn<T = any> {
     value: T | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-form-manage",
-  "version": "1.0.6-beta.2",
+  "version": "1.0.6-beta.4",
   "description": "Lightweight React form management with list and listener support.",
   "license": "MIT",
   "type": "module",

package/src/App.tsx

@@ -1,6 +1,7 @@
 import { Button, Input } from "antd";
 import { useEffect } from "react";
 import FormItem from "./components/Form/FormItem";
+import FormList from "./components/Form/FormList";
 import InputWrapper from "./components/Form/InputWrapper";
 import Form, { useForm } from "./providers/Form";
 
@@ -9,14 +10,19 @@ const App = () => {
 
   useEffect(() => {
     if (form) {
-      setTimeout(() => {
-        form.setFieldValue("TestData", "HelloWorld");
-      }, 500);
+      // setTimeout(() => {
+      //   form.setFieldValue("TestData", "HelloWorld");
+      // }, 500);
     }
   }, [form]);
   return (
     <div>
       <Form
+        initialValues={{
+          TestData: "",
+          numericCode: "",
+          arr: [{ el: "Item 1" }, { el: "Item 2" }],
+        }}
         onFinish={(values) => {
           console.log(values);
         }}
@@ -27,7 +33,72 @@ const App = () => {
             <Input />
           </InputWrapper>
         </FormItem>
+
+        <FormItem
+          name={"numericCode"}
+          rules={[
+            { required: true, message: "Vui lòng nhập mã" },
+            {
+              pattern: /^\d+$/,
+              message: "Chỉ cho phép chuỗi số",
+            },
+          ]}
+        >
+          <InputWrapper>
+            <Input placeholder="Mã chỉ gồm số" style={{ width: 200 }} />
+          </InputWrapper>
+        </FormItem>
+        <FormList
+          initialValues={[
+            {
+              el: "",
+            },
+          ]}
+          name="arr"
+        >
+          {(fields, { add, remove, move }) => (
+            <div>
+              {fields.map((field, index) => (
+                <div key={field.key} style={{ marginBottom: 8 }}>
+                  <FormItem name={`${field.name}.el`}>
+                    <InputWrapper>
+                      <Input placeholder="Item value" style={{ width: 200 }} />
+                    </InputWrapper>
+                  </FormItem>
+                  <Button
+                    onClick={() => remove({ index })}
+                    style={{ marginLeft: 8 }}
+                  >
+                    Remove
+                  </Button>
+                  {index > 0 && (
+                    <Button
+                      onClick={() => move({ from: index, to: index - 1 })}
+                      style={{ marginLeft: 8 }}
+                    >
+                      Move Up
+                    </Button>
+                  )}
+                  {index < fields.length - 1 && (
+                    <Button
+                      onClick={() => move({ from: index, to: index + 1 })}
+                      style={{ marginLeft: 8 }}
+                    >
+                      Move Down
+                    </Button>
+                  )}
+                </div>
+              ))}
+              <Button onClick={() => add(fields.length)}>Add Item</Button>
+            </div>
+          )}
+        </FormList>
         <Button htmlType="submit">Submit</Button>
+        <Button
+          onClick={() => {
+            form?.resetFields?.();
+          }}
+        ></Button>
       </Form>
     </div>
   );

package/src/components/Form/FormItem.tsx

@@ -1,5 +1,6 @@
 import { cloneElement, useRef, useState } from "react";
 import type { ReactElement } from "react";
+import type { ValidationRule } from "../../types/public";
 import { v4 } from "uuid";
 import useFormItemControl from "../../hooks/useFormItemControl";
 
@@ -9,7 +10,7 @@ export interface FormItemProps {
   formName?: string;
   initialValue?: any;
   formItemId?: string;
-  rules?: any[];
+  rules?: ValidationRule[];
   valuePropName?: string;
   getValueFromEvent?: (event: any) => any;
 }

package/src/hooks/useFormItemControl.ts

@@ -25,6 +25,7 @@ import {
 } from "../stores/formStore";
 
 import type { FormInstance } from "../stores/formStore";
+import type { ValidationRule } from "../types/public";
 
 type AnyObject = Record<string, any>;
 
@@ -34,7 +35,7 @@ interface UseFormItemControlProps {
   name?: string;
   initialValue?: any;
   formItemId?: string;
-  rules?: any[];
+  rules?: ValidationRule[];
   elementRef?: RefObject<any> | null;
 }
 
@@ -59,7 +60,14 @@ export default function useFormItemControl<T = any>({
   elementRef,
 }: UseFormItemControlProps): UseFormItemControlReturn {
   const contextForm = useFormContext();
-  const { value, setData, getCacheData, getFormValues } = useFormStore(
+  const {
+    value,
+    setData,
+    getCacheData,
+    getFormValues,
+    getFormState,
+    isStateInitied,
+  } = useFormStore(
     useShallow((state) => {
       return {
         value: get(
@@ -69,6 +77,11 @@ export default function useFormItemControl<T = any>({
         setData: state.setData,
         getCacheData: state.getCacheData,
         getFormValues: state.getFormValues,
+        getFormState: state.getFormState,
+        isStateInitied:
+          state.formStates?.[
+            formName || form?.formName || contextForm?.formName
+          ]?.isInitied,
       };
     }),
   );
@@ -130,6 +143,7 @@ export default function useFormItemControl<T = any>({
       name,
       value,
     );
+    onChange(value, { notTriggerDirty: true });
   };
 
   const onFocus = () => {
@@ -283,6 +297,16 @@ export default function useFormItemControl<T = any>({
             }
           }
 
+          // Custom pattern
+          if (r.pattern && !r.pattern.test(fieldValue || "")) {
+            listErrors.push({
+              ruleName,
+              message: r.message,
+            });
+
+            return;
+          }
+
           // Password
           if (r.isPassword && !IS_PASSWORD_REGEX.test(fieldValue)) {
             // tempMessage.push(IS_PASSWORD_INVALID_MESSAGE);
@@ -478,17 +502,22 @@ export default function useFormItemControl<T = any>({
     // console.log("Init item value: ", name, value, internalInitValue);
     // console.log("internalInitValue: ", internalInitValue);
 
-    if (!value) {
-      if (!internalInitValue) {
-        if (!isNil(initialValue)) {
-          console.log("On init data", initialValue);
-          onInitData(initialValue);
+    if (isStateInitied) {
+      // console.log("Skip set init data when form is resetting");
+
+      if (isNil(value)) {
+        if (isNil(internalInitValue)) {
+          if (isNil(initialValue)) {
+            console.log("On init data", initialValue);
+            onInitData(initialValue);
+          }
+        } else {
+          onChange(internalInitValue, { notTriggerDirty: true });
         }
-      } else {
-        onChange(internalInitValue);
       }
+      return;
     }
-  }, [internalInitValue]);
+  }, [isStateInitied]);
 
   useEffect(() => {
     if (!listener) {

package/src/index.ts

@@ -4,6 +4,7 @@ import Form, {
   useSubmitDataWatch,
   useFormStateWatch,
   type FormProps,
+  type ValidationRule,
 } from "./providers/Form";
 
 import FormItem, { type FormItemProps } from "./components/Form/FormItem";
@@ -30,6 +31,7 @@ export {
   type FormItemProps,
   type FormListProps,
   type InputWrapperProps,
+  type ValidationRule,
 };
 
 export default Form;