@simpleform/form 1.0.1 → 1.0.3

package/README.md

@@ -1,10 +1,215 @@
 # `@simpleform/form`
+English | [中文说明](./README_CN.md)
 
-> TODO: description
+[![](https://img.shields.io/badge/version-1.0.1-green)](https://www.npmjs.com/package/@simpleform/form)
 
-## Usage
+> The underlying form component automatically injects `value` and `onChange` into the target control to display and update the form values.
 
+# Matters
+- The css style file needs to be introduced before it can be used, for example: `import '@simpleform/form/lib/css/main.css'`;
+
+# Form.Item
+
+The smallest unit of a component in a form, and nodes as an object can be nested within each other.
+
+- Provides styles, as well as `value` (or set via `valueProp`) and `onChange` two-way bindings.
+- You can customize `onChange` in outside, but you can only set the form value via an instance method such as `form.setFieldValue`.
+- Custom form validation rules can be provided with the form validation rules property `rules`.
+- When a non-form component or node is added outside the input form control, bind the target control by adding `data-type="ignore"` to filter the non-target node or by setting `data-name` to mark the target input form.
+
+# Form.List
+
+The `Form.Item` component acts as an item in the `Form.List` array type and is combined to form an array
+
+- Only `Form.Item` items are recognised in `Form.List`, The `name` field of `Form.Item`, if set, is the field property in the array, if not, it defaults to the array serial number.
+- The `rules` provided by `Form.List` are valid for all input items in the array, but have a lower priority than the `rules` of the `Form.Item` in the array
+
+## install
+- [Node.js](https://nodejs.org/en/) Version >= 18.18.2
+- [react](https://nodejs.org/en/) Version >= 16.8.0
+```bash
+npm install @simpleform/form --save
+# or
+yarn add @simpleform/form
 ```
 
-// TODO: DEMONSTRATE API
+## base
+
+```javascript
+import React from "react";
+import { Form, useSimpleForm, useFormValues } from "@simpleform/form";
+import '@simpleform/form/lib/css/main.css';
+import { Input, Select } from "antd";
+
+export default function Demo() {
+
+  const form = useSimpleForm();
+  const formvalues = useFormValues(form, ['name1', 'name2'])
+  console.log(formvalues, 'formvalues')
+
+  const onSubmit = async (e) => {
+    e.preventDefault();
+    const { error, values } = await form.validate();
+    console.log(error, values, 'error ang values');
+  };
+
+  const validator = (value) => {
+    if (value?.length < 2) {
+      return Promise.reject(new Error('length is < 2'));
+    }
+  }
+
+  return (
+    <Form initialValues={{ name1: 1111 }} form={form} onSubmit={onSubmit}>
+      <Form.Item label="Name1" name="name1" rules={[{ required: true, message: 'name1 is Empty' }, { validator: validator, message: 'validator error' }]}>
+        <div data-type="ignore">
+          <input />
+        </div>
+      </Form.Item>
+      <Form.Item label="object" name="name2.a" rules={[{ required: true, message: 'name2.a is empty' }]}>
+        <input />
+      </Form.Item>
+      <Form.Item label="list" name="name3[0]" rules={[{ required: true, message: 'name3[0] is empty' }]}>
+        <input />
+      </Form.Item>
+      <Form.Item label="">
+        <button>Submit</button>
+      </Form.Item>
+    </Form>
+  );
+};
+```
+## Form.List
+
+```javascript
+import React from "react";
+import { Form, useSimpleForm } from "@simpleform/form";
+import '@simpleform/form/lib/css/main.css';
+import { Input, Select } from "antd";
+
+export default function Demo() {
+
+  const form = useSimpleForm();
+
+  const onSubmit = async (e) => {
+    e.preventDefault();
+    const { error, values } = await form.validate();
+    console.log(error, values, 'error ang values');
+  };
+
+  const validator = async (value) => {
+    if (value?.length < 2) {
+      return Promise.reject(new Error('length is < 2'));
+    }
+  }
+
+  return (
+    <Form form={form} onSubmit={onSubmit}>
+      <Form.List name="list">
+        <Form.Item
+          rules={[
+            { required: true, message: "list's one is Empty" },
+            { validator: validator, message: "custome tips" },
+          ]}
+          >
+          <Input />
+        </Form.Item>
+        <Form.Item
+          rules={[{ required: true, message: "list's two is Empty" }]}
+        >
+          <Input />
+        </Form.Item>
+      </Form.List>
+      <Form.Item label="">
+        <button>Submit</button>
+      </Form.Item>
+    </Form>
+  );
+};
+
 ```
+
+## APIs
+
+### Default field display component
+
+- `className` `string` class name, `optional`.
+- `label` `string` label, `optional`.
+- `labelStyle` `CSSProperties` custom label's style, `optional`.
+- `labelWidth` `CSSProperties['width']`, the width of the label label.
+- `labelAlign` `CSSProperties['textAlign']`, the label label's textAlign property.
+- `inline` `boolea`, Whether or not field display components have inline layout.
+- `layout` `'horizontal'|'vertical'` field’s display components set the layout type, the default value is `horizontal`.
+- `colon` `boolean` whether add colon
+- `required` `boolean` Indicates that the value of the field is required `optional`。
+- `gutter` `number` The distance between field's display component custom labels and form components, `optional`.
+- `error` `string` form field displays the component's error message field.
+- `suffix` `React.ReactNode` Suffix node, `optional`.
+- `footer` `React.ReactNode` bootom node, `optional`.
+- `tooltip` `string` Tip icon to prompt for information. `optional`.
+- `compact` `boolean` Whether or not compact, will remove the component's `margin-bottom`. `optional`.
+
+### Form Props
+Inherited field display component
+
+- `className` The class name of the form element, `optional`.
+- `form` The form data store, `required`.
+- `tagName` Replace the element tag name of the form, default `form` tag
+- `initialValues` The initial value of the form, which is overridden by the `initialValue` of the form field, Note that this value can only initialise the form `optional`.
+- `onSubmit` `form` tag triggers the reset default event, only `button` tags that provide `htmlType=submit` can trigger `optional`.
+- `onReset` `form` tag triggers the reset default event, only `button` tags that provide `htmlType=reset` can trigger `optional`.
+- `onFieldsChange` The event function when a form changes onChange will only be triggered by the control's active `onChange`, not by `form.setFieldValue` and `form.setFieldsValue`, avoiding circular calls。`optional`.
+- `onValuesChange` Listening for changes in form values.`optional`.
+- `watch` Listens for changes in the value of any field.
+
+### Form.Item Props
+Inherited field display component
+
+- `className` Form field class name, `optional`.
+- `component` field display component. 
+- `name` Form field name, `optional`.
+- `trigger` Sets the event name of the form field to collect form values, default `onChange`.
+- `validateTrigger` Sets the event for trigger form field validation, default `onChange`.
+- `valueProp` The field name of the value in the callback function object, the default value is `'value'`.
+- `valueGetter` A function to format the output form value, used with `valueSetter`, `optional`.
+- `valueSetter` function to format input form value, used with `valueGetter`, `optional`.
+- `rules` Checksum rules for form fields `optional`.
+- `initialValue` The initial value of the form field, note that this value is different from `value` when the form is rendered for the first time.
+- `onFieldsChange` The event function when the value of the control changes will only be triggered by the control's active `onChange`, not by `form.setFieldValue` and `form.setFieldsValue`, avoiding circular calls. `optional`.
+- `onValuesChange` Listening for changes in form values.`optional`。
+- `errorClassName` add a custom class name when there is an error message, `optional`.
+
+### Form.List Props
+Inherited field display component
+
+- `className` Form field class name, `optional`.
+- `component` field display component. 
+- `name` Form field name, `optional`.
+- `initialValue` Form field initial value, Note that this value can only initialise the form `optional`.
+- `rules` Checksum rules for form fields `optional`.
+
+### rules
+The rules in the fields of the values in `rules` perform the checks in order, and only one rule can be set for each item in `rules`.
+- `validateTrigger` `string` Event to trigger validate form rules, default `onChange`.
+- `message` `string` Default error message when a check rule reports an error `optional`。
+- `required` `boolean` The required symbol is marked, and a `required` attribute of `true` in `rules` also automatically adds the required symbol `optional`。
+- `validator` `(value) => void | boolean` Custom check function, `value` is the current control value `optional`.
+- `pattern` `RegExp | string` Expression check, error if does not match `optional`.
+- `whitespace` `boolean` space check `optional`.
+- `max` `number` Maximum length for string type; maximum length for number type; maximum length for array type `optional`.
+- `min` `number` minimum length for `string` type; minimum value for `number` type; minimum length for `array` type. `optional`.
+
+### SimpleForm
+To create an instance of `form` via `useSimpleForm`, use the following:
+- `form.getFieldValue(path?: string)` Returns the value of the form field for which `path` is specified, or the value of the whole form without `name`.
+- `form.setFieldValue(path, value)` Update the value of a form field
+- `form.setFieldsValue(obj: Partial<T>)` Set the value of the form field (override).
+- `form.reset(values?: Partial<T>)` Reset the form.The value can be passed to reset to the target value.
+- `form.validate(path?: string)` Checks form and returns error messages and form values.
+- `form.getFieldError(path?: string)` Returns the target's error message or all error messages.
+
+### Hooks
+
+- `useSimpleForm(defaultValues)` create `new SimpleForm()`
+- `useFormError(form: SimpleForm, path?: string)` Use hooks to get the specified form error.
+- 3.0.12 `useFormValues(form: SimpleForm, path?: string | string[])` Use hooks to get the specified form values.

package/README_CN.md

@@ -0,0 +1,216 @@
+# `@simpleform/form`
+
+[English](./README.md) | 中文说明
+
+[![](https://img.shields.io/badge/version-1.0.1-green)](https://www.npmjs.com/package/@simpleform/form)
+
+> 表单底层组件，自动注入`value`和`onChange`到目标控件中，完成表单值的显示和更新.
+
+# Matters
+ - 在使用之前需要先引入css样式文件，例：`import '@simpleform/form/lib/css/main.css'`;
+
+# Form.Item
+
+表单域组件，用于双向绑定目标控件。
+
+- 双向绑定：`value`(或通过`valueProp`设置)和`onChange`双向绑定，`name`字段为目标属性。
+- 更新表单值：可通过`form.setFieldValue`等实例方法设置表单值。
+- 可以提供表单校验规则属性`rules`，进行自定义表单校验规则。
+- 当输入表单控件外面添加了非表单组件或节点，通过添加`data-type="ignore"`过滤非目标节点或设置`data-name`标记目标节点来绑定目标控件。
+
+# Form.List
+
+`Form.Item`组件作为`Form.List`数组类型中的项，组合形成一个数组
+
+- `Form.List`中只识别`Form.Item`项，`Form.Item`的`name`字段如果设置，则为数组中的字段属性，如果不设置，则默认为数组序号。
+- `Form.List`提供的`rules`校验规则，对数组中的所有输入项都有效，但优先级低于数组中的`Form.Item`的`rules`规则
+
+## 安装
+- [Node.js](https://nodejs.org/en/) Version >= 18.18.2
+- [react](https://nodejs.org/en/) Version >= 16.8.0
+```bash
+npm install @simpleform/form --save
+# 或者
+yarn add @simpleform/form
+```
+
+## 基本使用
+
+```javascript
+import React from "react";
+import { Form, useSimpleForm, useFormValues } from "@simpleform/form";
+import '@simpleform/form/lib/css/main.css';
+import { Input, Select } from "antd";
+
+export default function Demo() {
+
+  const form = useSimpleForm();
+  const formvalues = useFormValues(form, ['name1', 'name2'])
+  console.log(formvalues, 'formvalues')
+
+  const onSubmit = async (e) => {
+    e.preventDefault();
+    const { error, values } = await form.validate();
+    console.log(error, values, 'error ang values');
+  };
+
+  const validator = (value) => {
+    if (value?.length < 2) {
+      return Promise.reject(new Error('length is < 2'));
+    }
+  }
+
+  return (
+    <Form initialValues={{ name1: 1111 }} form={form} onSubmit={onSubmit}>
+      <Form.Item label="Name1" name="name1" rules={[{ required: true, message: 'name1 is Empty' }, { validator: validator, message: 'validator error' }]}>
+        <div data-type="ignore">
+          <input />
+        </div>
+      </Form.Item>
+      <Form.Item label="object" name="name2.a" rules={[{ required: true, message: 'name2.a is empty' }]}>
+        <input />
+      </Form.Item>
+      <Form.Item label="list" name="name3[0]" rules={[{ required: true, message: 'name3[0] is empty' }]}>
+        <input />
+      </Form.Item>
+      <Form.Item label="">
+        <button>Submit</button>
+      </Form.Item>
+    </Form>
+  );
+};
+```
+
+## Form.List
+
+```javascript
+import React from "react";
+import { Form, useSimpleForm } from "@simpleform/form";
+import '@simpleform/form/lib/css/main.css';
+import { Input, Select } from "antd";
+
+export default function Demo() {
+
+  const form = useSimpleForm();
+
+  const onSubmit = async (e) => {
+    e.preventDefault();
+    const { error, values } = await form.validate();
+    console.log(error, values, 'error ang values');
+  };
+
+  const validator = async (value) => {
+    if (value?.length < 2) {
+      return Promise.reject(new Error('length is < 2'));
+    }
+  }
+
+  return (
+    <Form form={form} onSubmit={onSubmit}>
+      <Form.List name="list">
+        <Form.Item
+          rules={[
+            { required: true, message: "list's one is Empty" },
+            { validator: validator, message: "custome tips" },
+          ]}
+          >
+          <Input />
+        </Form.Item>
+        <Form.Item
+          rules={[{ required: true, message: "list's two is Empty" }]}
+        >
+          <Input />
+        </Form.Item>
+      </Form.List>
+      <Form.Item label="">
+        <button>Submit</button>
+      </Form.Item>
+    </Form>
+  );
+};
+```
+
+## APIs
+
+### 默认的表单域显示组件的属性
+- `className` `string` 类名，`可选`。
+- `label` `string` 标签，`可选`。
+- `labelStyle` `CSSProperties` 自定义`label`样式，`可选`。
+- `labelWidth` `CSSProperties['width']`, label标签的宽度。
+- `labelAlign` `CSSProperties['textAlign']`, label标签的textAlign属性。
+- `inline` `boolean`, 是否设置行内布局。
+- `layout` `'horizontal'|'vertical'` 设置布局类型，默认值为`horizontal`。
+- `colon` `boolean` 是否添加冒号
+- `required` `boolean` 是否显示星号，不包含表单校验，仅用于显示，默认值为`false`。
+- `gutter` `number` 自定义`label`标签和表单组件间的距离，`可选`。
+- `error` `string` 表单域显示组件的报错信息字段。
+- `suffix` `React.ReactNode` 后缀节点，`可选`。
+- `footer` `React.ReactNode` 底部节点，`可选`。
+- `tooltip` `string` 提示图标，可以提示信息。`可选`。
+- `compact` `boolean` 是否紧凑，会去掉组件的`margin-bottom`。`可选`。
+
+### Form Props
+继承表单域显示组件(`component`)的props
+
+- `className` 表单元素类名，`可选`。
+- `form` 表单数据管理，`必须`。
+- `tagName` 更换表单的元素标签名, 默认`form`标签
+- `initialValues` 表单的初始值，会被表单域的`initialValue`覆盖, 注意此值只能初始化表单赋值`可选`。
+- `onSubmit` `form`标签提交事件, 只有提供`htmlType=submit`的`button`标签才可以触发，`可选`。
+- `onReset` `form`标签触发重置默认值触发事件, 只有`htmlType=reset`的`button`标签才可以触发 `可选`。
+- `onFieldsChange` 表单域 `onChange` 变化时的事件函数，只会被控件主动`onChange`触发，不会被`form.setFieldValue`和`form.setFieldsValue`触发, 避免循环调用。`可选`。
+- `onValuesChange` 监听表单值的变化。`可选`。
+- `watch` 监听任意字段的值的变化。
+
+
+### Form.Item Props
+继承表单域显示组件(`component`)的props
+
+- `className` 表单域类名，`可选`。
+- `component` 表单域显示组件。
+- `name` 表单域字段名，`可选`。
+- `trigger` 设置表单域收集表单值的事件名，默认`onChange`.
+- `validateTrigger` 设置表单域校验的触发事件, 默认`onChange`.
+- `valueProp` 回调函数对象中值的字段名，默认值为`'value'`。
+- `valueGetter` 格式化输出表单值的函数，配合`valueSetter`使用, `可选`。
+- `valueSetter` 格式化输入表单值的函数，配合`valueGetter`使用, `可选`。
+- `rules` 表单域的校验规则 `可选`。
+- `initialValue` 表单域的初始值，注意此值和`value`不同，只能表单第一次渲染时赋值`可选`。
+- `onFieldsChange` 控件的值变化时的事件函数，只会被控件主动`onChange`触发，不会被`form.setFieldValue`和`form.setFieldsValue`触发, 避免循环调用。`可选`。
+- `onValuesChange` 监听表单值的变化。`可选`。
+- `errorClassName` 控件当有错误信息时，添加一个自定义类名，`可选`。
+
+### Form.List Props
+继承表单域显示组件(`component`)的props
+
+- `className` 表单域类名，`可选`。
+- `component` 表单域显示组件。
+- `name` 表单域字段名，`可选`。
+- `initialValue` 表单域的初始值，注意此值和`value`不同，只能初始化表单赋值`可选`。
+- `rules` 表单域的校验规则 `可选`。
+
+### 表单的rules中的校验字段
+`rules`中的值的字段中的规则会按照顺序执行校验，`rules`中每一项只能设置一种规则。
+- `validateTrigger` `string` 校验表单规则的触发事件, 默认`onChange`.
+- `message` `string` 校验规则报错时，默认的报错信息 `可选`。
+- `required` `boolean` 标记必填符号, 同时`rules`中的`required`属性为`true`也自动添加必填标记 `可选`。
+- `validator` `(value) => void | boolean` 自定义校验函数, `value`为当前控件值 `可选`。
+- `pattern` `RegExp | string` 表达式校验，不符合则报错 `可选`。
+- `whitespace` `boolean` 空格校验 `可选`。
+- `max` `number` 表单值为`string`类型时字符串最大长度；`number` 类型时为最大值；`array` 类型时为数组最大长度 `可选`。
+- `min` `number` 表单值为`string`类型时字符串最小长度；`number` 类型时为最小值；`array` 类型时为数组最小长度 `可选`。
+
+### SimpleForm
+ 通过`useSimpleForm`创建`form`实例, 可使用以下方法:
+- `form.getFieldValue(path?: string)` 返回指定`path`的表单域的值，不指定`path`返回整个表单的值。
+- `form.setFieldValue(path, value)` 更新表单域的值
+- `form.setFieldsValue(obj: Partial<T>)` 设置表单域的值(覆盖)。
+- `form.reset(values?: Partial<T>)` 重置表单, 可以传值重置为目标值。
+- `form.validate(path?: string)` 校验表单，并返回错误信息和表单值。
+- `form.getFieldError(path?: string)` 返回目标的错误信息或所有的错误信息。
+
+### Hooks
+
+- `useSimpleForm(defaultValues)`: 创建 `new SimpleForm()`
+- `useFormError(form: SimpleForm, path?: string)`: 使用 hooks 获取指定的报错信息。
+- 3.0.12 `useFormValues(form: SimpleForm, path?: string | string[])`: 使用 hooks 获取指定的表单值。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simpleform/form",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "simple form component",
   "author": "mezhanglei <496623925@qq.com>",
   "homepage": "https://github.com/mezhanglei/simpleform#readme",
@@ -24,7 +24,9 @@
   },
   "publishConfig": {
     "access": "public",
-    "registry": "https://registry.npmjs.org/"
+    "registry": "https://registry.npmjs.org/",
+    "node-version": ">14.0.0",
+    "npm-version": ">6.0.0"
   },
   "scripts": {
     "build": "cross-env NODE_ENV=prod webpack --progress --config ./webpack/webpack.prod.js && tsc -d",