react-form-manage 1.0.0

package/README.md

@@ -0,0 +1,193 @@
+# react-form-manage
+
+Thư viện form nhẹ dành cho React — hỗ trợ form, field, list (array fields), và cơ chế listener để giảm re-render.
+
+Phiên bản này xuất phát từ mã nguồn JS. Typings (.d.ts) được cung cấp trong `src/types/components.d.ts`.
+
+---
+
+## Cài đặt
+
+```bash
+npm install react-form-manage
+# hoặc nếu bạn dùng yarn
+yarn add react-form-manage
+```
+
+**Lưu ý:** `react` và `react-dom` phải là `peerDependencies` của project sử dụng thư viện này. Ngoài ra `antd` chỉ cần khi bạn dùng component `AntInput`.
+
+---
+
+## Export chính
+
+Thư viện cung cấp (named/default exports):
+
+- `default` export: `Form` (component provider)
+- `FormItem` (component)
+- `FormList` (component)
+- `Input` (basic HTML input wrapper)
+- `AntInput` (antd Input wrapper)
+- `InputWrapper` (UI wrapper để hiển thị lỗi)
+- Hooks: `useForm`, `useWatch`, `useSubmitDataWatch`, `useFormStateWatch`, `useFormItemControl`, `useFormListControl`
+
+Ví dụ import:
+
+```javascript
+import Form, { FormItem, FormList, Input, InputWrapper } from 'react-form-manage';
+```
+
+---
+
+## Quick Start
+
+Ví dụ form đơn giản:
+
+```jsx
+import React from 'react';
+import Form, { FormItem } from 'react-form-manage';
+import Input from './path-to-package/Input';
+
+function Example() {
+  return (
+    <Form formName="myForm" initialValues={{ name: '' }} onFinish={(values) => console.log('submit', values)}>
+      <FormItem name="name">
+        <Input />
+      </FormItem>
+      <button type="submit">Submit</button>
+    </Form>
+  );
+}
+
+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`.
+
+---
+
+## Form API / Programmatic usage
+
+Bạn có thể lấy instance form để gọi phương thức chương trình như `submit`, `resetFields`, `setFieldValue`…
+
+Ví dụ sử dụng hook attached trên `Form`:
+
+```jsx
+import React from 'react';
+import Form from 'react-form-manage';
+
+function CtrlExample() {
+  const [form] = Form.useForm('myForm'); // hoặc useForm('myForm')
+
+  return (
+    <div>
+      <button onClick={() => form?.submit?.()}>Submit programmatically</button>
+      <button onClick={() => form?.resetFields?.()}>Reset</button>
+    </div>
+  );
+}
+```
+
+Methods available on the form instance (populated by `Form` provider):
+
+- `submit()` / `submitAsync()`
+- `resetFields()`
+- `setFieldValue(name, value)`
+- `setFieldValues(values)`
+- `getFieldValue(name)` / `getFieldValues(names)`
+- `setFieldFocus(name)`
+- `getFieldErrors(names)`
+
+---
+
+## FormList (Array field)
+
+`FormList` là render-prop component cung cấp `listFields` và các action `add`, `remove`, `move`.
+
+Ví dụ:
+
+```jsx
+import React from 'react';
+import Form, { FormList, FormItem } from 'react-form-manage';
+import Input from './Input';
+
+function ListExample() {
+  return (
+    <Form formName="listForm">
+      <FormList name="items">{(fields, { add, remove }) => (
+        <div>
+          {fields.map((f, i) => (
+            <div key={f.key}>
+              <FormItem name={f.name}>
+                <Input />
+              </FormItem>
+              <button onClick={() => remove({ index: i })}>Remove</button>
+            </div>
+          ))}
+          <button onClick={() => add()}>Add</button>
+        </div>
+      )}</FormList>
+    </Form>
+  );
+}
+```
+
+Lưu ý: `FormList` quản lý các `key` nội bộ và push các mục cần cleanup vào `cleanUpStack` khi xóa phần tử — thư viện đã cung cấp cơ chế cleanup trong `Form` provider.
+
+---
+
+## Hooks (tóm tắt)
+
+- `useForm(formNameOrFormInstance)` — trả về form instance đã đăng ký.
+- `useWatch(name, formNameOrFormInstance)` — subscribe giá trị field.
+- `useSubmitDataWatch` — watch dữ liệu submit cuối cùng.
+- `useFormStateWatch` — watch state của form (isInitied, submitState…).
+- `useFormItemControl` — internal hook dùng bởi `FormItem` (trả về `{ value, onChange, state, errors, onFocus, isDirty }`).
+- `useFormListControl` — internal hook dùng bởi `FormList` (trả về `{ listFields, add, remove, move }`).
+
+Bạn hãy xem `src/types/components.d.ts` nếu muốn biết các kiểu TypeScript sẵn có.
+
+---
+
+## TypeScript
+
+Thư viện đi kèm file typing (hand-written) tại `src/types/components.d.ts`.
+
+Nếu bạn muốn tự sinh `.d.ts` từ JS, có thể thêm `tsconfig.types.json` với `allowJs` + `declaration` và chạy `tsc --emitDeclarationOnly`.
+
+---
+
+## Lưu ý khi publish
+
+- Đặt `react` và `react-dom` vào `peerDependencies`.
+- Đảm bảo `types` trong `package.json` trỏ tới file `.d.ts` (ví dụ `src/types/components.d.ts` hoặc `dist/index.d.ts`).
+- Kiểm tra `npm pack` trước khi `npm publish`.
+
+---
+
+## Contributing
+
+1. Fork repository
+2. Tạo branch cho tính năng/fix
+3. Mở PR với mô tả thay đổi
+
+---
+
+## 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.