@regenbio/regenbio-components-react 1.2.14 → 1.2.16

package/packages/form/src/components/Group/index.en-US.md

@@ -0,0 +1,326 @@
+---
+title: Structured data
+atomId: ProFormList
+order: 1
+
+nav:
+  title: Components
+---
+
+# ProFormFields
+
+ProForm comes with a significant number of form items, which are essentially a combination of Form.Item and components. Each form item supports the `fieldProps` property to support setting the `props` of the input component. We support pass-through of `placeholder`, so you can set `placeholder` directly on the component.
+
+Each form item also supports `readonly`, which has different read-only styles for different components, making `readonly` display more friendly compared to `disable`. The generated dom is also smaller, e.g. ProFormDigit automatically formats decimal digits.
+
+ProFormText is the product of FormItem + Input and can be analogous to the following code.
+
+```tsx | pure
+const ProFormText = (props) => {
+  return (
+    <ProForm.Item {. .props}>
+      <Input placeholder={props.placeholder} {. .props.fieldProps} />
+    </ProForm.Item
+  );
+};
+```
+
+So the props we set for ProFormText are actually for Form.Item, and the fieldProps are for the included Input, remember.
+
+In addition to display type form items, we also provide form items for combining data:
+
+## ProFormList
+
+ProFormList is basically the same as the [Form.List](https://ant.design/components/form/#Form.List) API. It adds its own operation buttons: delete and copy, and it also includes a `new row` button.
+
+```tsx | pure
+<ProFormList
+  name="users"
+  initialValue={[
+    {
+      useMode: 'chapter',
+    },
+  ]}
+  creatorButtonProps={{
+    position: 'top',
+    creatorButtonText: 'Building a line',
+  }}
+  creatorRecord={{
+    useMode: 'none',
+  }}
+>
+  <ProFormSelect
+    key="useMode"
+    options={[
+      {
+        value: 'chapter',
+        label: 'Valid after stamping',
+      },
+      {
+        value: 'none',
+        label: 'Not effective',
+      },
+    ]}
+    width="md"
+    name="useMode"
+    label="Contract agreement effective method"
+  />
+</ProFormList>
+```
+
+### ProFormList API
+
+| Parameters | Description | Type | Default Value |
+| --- | --- | --- | --- |
+| creatorRecord | Default value of a new line | `Record<string, any>` | - |
+| creatorButtonProps | Configuration of a new line of buttons | `buttonProps & {creatorButtonText:string,position:"top"\|"bottom" }` | `{creatorButtonText:"Create a new line"}` |
+| label | Same as From.Item | `ReactNode` | - |
+| name | The value of list in the form, required | `NamePath` | - |
+| alwaysShowItemLabel | always show label in Item | `boolean` | - |
+| actionRef | The built-in operation of the current List, you can add, delete, modify and check list items | `{add,remove,move,get}` | - |
+| actionGuard | FormItem's interceptor, including deletion and addition interception, you can use actionRef to get the value of the current row | `{beforeAddRow:(index)=>boolean,beforeRemoveRow:(index)=>boolean}` | - |
+| min | The minimum number of entries, if the current data entry is less than this number, it cannot be deleted | `number` | - |
+| max | The maximum number of entries, when adding or copying, if the current data entry exceeds this number, it cannot be added or copied | `number` | - |
+| copyIconProps | Copy button configuration, false to cancel | `{ Icon?: React.FC<any>; tooltipText?: string; } \| false` | - |
+| deleteIconProps | Delete button configuration, false can cancel | `{ Icon?: React.FC<any>; tooltipText?: string; } \| false` | - |
+| actionRender | custom action button | `(field,action,defaultActionDom,count)=>React.ReactNode[]` | - |
+
+### actionRef Action item instance
+
+```tsx | pure
+const actionRef = useRef<
+  FormListActionType<{
+    name: string;
+  }>
+>();
+
+return (
+  /**
+   * @name gets the list operation instance
+   * @description can delete, add, move and other operations
+   *
+   * @example actionRef?.current.add?.({},1);
+   * @example actionRef?.current.remove?.(1);
+   * @example actionRef?.current.move?.(1,2);
+   * @example actionRef?.current.get?.(1);
+   */
+  <>
+    <Space>
+      <Button
+        type="primary"
+        onClick={() => {
+          const list = actionRef.current?.getList();
+          actionRef.current?.add({
+            name: 'New' + list?.length,
+          });
+        }}
+      >
+        add a line
+      </Button>
+      <Button
+        danger
+        onClick={() => {
+          actionRef.current?.remove(1);
+        }}
+      >
+        delete a line
+      </Button>
+      <Button
+        onClick={() => {
+          actionRef.current?.move(1, 0);
+        }}
+      >
+        move to the first line
+      </Button>
+      <Button
+        type="dashed"
+        onClick={() => {
+          const row = actionRef.current?.get(1);
+          console.log(row);
+        }}
+      >
+        Get a row of data
+      </Button>
+      <Button
+        type="dashed"
+        onClick={() => {
+          const row = actionRef.current?.getList();
+          console.log(row);
+        }}
+      >
+        get all data
+      </Button>
+    </Space>
+    <ProFormList actionGuard={actionGuard} actionRef={actionRef}>
+      <ProFormText key="useMode" name="name" label="name" />
+    </ProFormList>
+  </>
+);
+```
+
+### actionGuard interceptor
+
+actionGuard can intercept list operations, and now there are two events `beforeAddRow` and `beforeRemoveRow`.
+
+```tsx | pure
+const actionRef = useRef<
+  FormListActionType<{
+    name: string;
+  }>
+>();
+const actionGuard = {
+  beforeAddRow: async (defaultValue, insertIndex, count) => {
+    return new Promise((resolve) => {
+      console.log(defaultValue?.name, insertIndex, count);
+      setTimeout(() => resolve(true), 1000);
+    });
+  },
+  beforeRemoveRow: async (index, count) => {
+    const row = actionRef.current?.get(index as number);
+    console.log('--->', index, count, row);
+    return new Promise((resolve) => {
+      if (index === 0) {
+        resolve(false);
+        return;
+      }
+      setTimeout(() => resolve(true), 1000);
+    });
+  },
+};
+return (
+  <ProFormList actionGuard={actionGuard} actionRef={actionRef}>
+    <ProFormText key="useMode" name="name" label="name" />
+  </ProFormList>
+);
+```
+
+### actionRender custom action button
+
+```tsx | pure
+  /**
+   * @name custom action button
+   *
+   * @example delete button
+   * actionRender:(field,action)=><a onClick={()=>action.remove(field.name)}>remove</a>
+   * @example can only add up to three new lines
+   * actionRender:(f,action,_,count)=><a onClick={()=>
+   * count>2?alert("Up to three lines!"):action.add({id:"xx"})}>delete
+   * </a>
+   */
+  actionRender?: (
+    field: FormListFieldData,
+    /**
+     * Operational ability
+     * @example action.add(data) add a new line
+     * @example action.remove(index) delete a line
+     * @example action.move(formIndex,targetIndex) move a row
+     */
+    action: FormListOperation,
+    /**
+     * Default operation dom
+     * [copy, delete]
+     */
+    defaultActionDom: ReactNode[],
+    /**
+     * There are currently several list items
+     */
+    count: number,
+  ) => ReactNode[];
+
+```
+
+### ProFormList RenderProps mode
+
+ProFormList supports passing in a method to get the information and shortcut operations of the current row, which is very convenient for complex linkage.
+
+```tsx | pure
+<ProFormList>
+  {(
+    // Basic information of the current row {name: number; key: number}
+    meta,
+    // current line number
+    index,
+    /**
+     * action
+     * @name some shortcut methods for manipulating rows
+     * @example add data to the second line action.add?.({},1);
+     * @example delete the second line action.remove?.(1);
+     * @example moved from 1 to 2: action.move?.(2,1);
+     * @example Get the data of the current row: action.getCurrentRowData() -> {id:"xxx",name:'123',age:18}
+     * @example Set current row data: {id:"123",name:'123'} -> action.setCurrentRowData({name:'xxx'}) -> {id:"123",name:'xxx' }
+     * @example clear the data of the current row: {id:"123",name:'123'} -> action.setCurrentRowData({name:undefined}) -> {id:"123"}
+     */
+    action,
+    // total number of rows
+    count,
+  ) => {
+    return (
+      <div key="row">
+        <ProFormText name="id" />
+        <ProFormText name="name" />
+      </div>
+    );
+  }}
+</ProFormList>
+```
+
+The types of these four parameters are defined as follows:
+
+```tsx | pure
+type RenderActionParams = {
+  /**
+   * @name The meta information of the current line
+   * @example {name: number; key: number}
+   */
+  meta: FormListFieldData;
+  /**
+   * @name the line number of the current line
+   */
+  index: number;
+  /**
+   * @name some shortcut methods for manipulating rows
+   * @example add data to the second line action.add?.({},1);
+   * @example delete the second line action.remove?.(1);
+   * @example moved from 1 to 2: action.move?.(2,1);
+   * @example Get the data of the current row: action.getCurrentRowData() -> {id:"xxx",name:'123',age:18}
+   * @example Set current row data: {id:"123",name:'123'} -> action.setCurrentRowData({name:'xxx'}) -> {id:"123",name:'xxx' }
+   * @example clear the data of the current row: {id:"123",name:'123'} -> action.setCurrentRowData({name:undefined}) -> {id:"123"}
+   */
+  action: FormListOperation & {
+    /**
+     * @name Get the data of the current row
+     * @example getCurrentRowData -> {id:"xxx",name:'123',age:18}
+     */
+    getCurrentRowData: () => any;
+    /**
+     * @name sets the data of the current row
+     * @example {id:"123",name:'123'} -> setCurrentRowData({name:'xxx'}) -> {id:"123",name:'123'}
+     * @example {id:"123",name:'123'} -> setCurrentRowData({name:undefined}) -> {id:"123"}
+     */
+    setCurrentRowData: (data: any) => void;
+  };
+  /**
+   * @name the total number of rows
+   */
+  count: number;
+};
+```
+
+## ProFormFieldSet
+
+ProFormFieldSet can combine the values of multiple children inside and store them in ProForm, and can be transformed at commit time via `transform`. Here is a simple usage to easily combine multiple input fields and format them to the desired data.
+
+```tsx | pure
+<ProFormFieldSet
+  name="list"
+  label="List of components"
+  // Two methods are supported, type="group" will be wrapped with input.group
+  // If not configured, use space by default
+  type="group"
+  transform={(value: any) => ({ startTime: value[0], endTime: value[1] })}
+>
+  <ProFormText width="md" />
+  <ProFormText width="md" />
+  <ProFormText width="md" />
+</ProFormFieldSet
+```

package/packages/form/src/components/Group/index.md

@@ -0,0 +1,373 @@
+---
+title: ProFormList - 数据结构化
+atomId: ProFormList
+order: 1
+---
+
+# 数据结构化
+
+我们还提供了用来进行结构化数据的录入:
+
+- ProFormList 录入结构化的多维数组数据。
+- ProFormFieldSet 录入结构化的一维数组数据。
+- ProFormDependency 数据依赖的相关组件
+
+## ProFormList
+
+ProFormList 与 [Form.List](https://ant.design/components/form-cn/#Form.List) API 基本相同，增加了自带的操作按钮：删除和复制，并且自带了了一个`新建一行`按钮。
+
+```tsx | pure
+<ProFormList
+  name="users"
+  initialValue={[
+    {
+      useMode: 'chapter',
+    },
+  ]}
+  creatorButtonProps={{
+    position: 'top',
+    creatorButtonText: '再建一行',
+  }}
+  creatorRecord={{
+    useMode: 'none',
+  }}
+>
+  <ProFormSelect
+    key="useMode"
+    options={[
+      {
+        value: 'chapter',
+        label: '盖章后生效',
+      },
+      {
+        value: 'none',
+        label: '不生效',
+      },
+    ]}
+    width="md"
+    name="useMode"
+    label="合同约定生效方式"
+  />
+</ProFormList>
+```
+
+### ProFormList API
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| itemRender | 自定义 Item，可以用来将 action 放到别的地方 | `(doms,listMeta)=> ReactNode` | - |
+| creatorRecord | 新建一行的默认值 | `Record<string, any> \| () => Record<string, any>` | - |
+| creatorButtonProps | 新建一行按钮的配置 | `buttonProps & { creatorButtonText:string,position:"top"\|"bottom" }` | `{creatorButtonText:"新建一行"}` |
+| label | 与 From.Item 相同 | `ReactNode` | - |
+| name | list 在 form 中的值，必填项 | `NamePath` | - |
+| alwaysShowItemLabel | Item 中总是展示 label | `boolean` | - |
+| actionRef | 当前 List 的自带操作，可以增删改查列表项 | `{add,remove,move,get}` | - |
+| actionGuard | FormItem 的拦截器，包含删除和添加的拦截，可以用 actionRef 拿到当前行的值 | `{beforeAddRow:(index)=>boolean,beforeRemoveRow:(index)=>boolean}` | - |
+| min | 最少条目，删除时如果当前数据条目少于该数则无法删除 | `number` | - |
+| max | 最多条目，新增或复制时如果当前数据条目多于该数则无法新增或复制 | `number` | - |
+| copyIconProps | 复制按钮的配置，false 可以取消 | `{ Icon?: React.FC<any>; tooltipText?: string; } \| false` | - |
+| deleteIconProps | 删除按钮的配置，false 可以取消 | `{ Icon?: React.FC<any>; tooltipText?: string; } \| false` | - |
+| actionRender | 自定义操作按钮 | `(field,action,defaultActionDom,count)=>React.ReactNode[]` | - |
+| onAfterAdd | 新增数据后的钩子 | `(defaultValue: StoreValue, insertIndex: number, count: number) => void` | - |
+| onAfterRemove | 删除数据后的钩子 | `(index: number, count: number) => void` | - |
+
+### actionRef 操作项目实例
+
+```tsx | pure
+const actionRef = useRef<
+  FormListActionType<{
+    name: string;
+  }>
+>();
+
+return (
+  /**
+   * @name 获取到 list 操作实例
+   * @description 可用删除，新增，移动等操作
+   *
+   * @example  actionRef?.current.add?.({},1);
+   * @example  actionRef?.current.remove?.(1);
+   * @example  actionRef?.current.move?.(1,2);
+   * @example  actionRef?.current.get?.(1);
+   */
+  <>
+    <Space>
+      <Button
+        type="primary"
+        onClick={() => {
+          const list = actionRef.current?.getList();
+          actionRef.current?.add({
+            name: '新增' + list?.length,
+          });
+        }}
+      >
+        增加一行
+      </Button>
+      <Button
+        danger
+        onClick={() => {
+          actionRef.current?.remove(1);
+        }}
+      >
+        删除一行
+      </Button>
+      <Button
+        onClick={() => {
+          actionRef.current?.move(1, 0);
+        }}
+      >
+        移动到第一行
+      </Button>
+      <Button
+        type="dashed"
+        onClick={() => {
+          const row = actionRef.current?.get(1);
+          console.log(row);
+        }}
+      >
+        获取一行数据
+      </Button>
+      <Button
+        type="dashed"
+        onClick={() => {
+          const row = actionRef.current?.getList();
+          console.log(row);
+        }}
+      >
+        获取所有数据
+      </Button>
+    </Space>
+    <ProFormList actionGuard={actionGuard} actionRef={actionRef}>
+      <ProFormText key="useMode" name="name" label="姓名" />
+    </ProFormList>
+  </>
+);
+```
+
+### actionGuard 拦截器
+
+actionGuard 可以拦截 list 的操作，现在有 `beforeAddRow` 和 `beforeRemoveRow` 两个事件。
+
+```tsx | pure
+const actionRef = useRef<
+  FormListActionType<{
+    name: string;
+  }>
+>();
+const actionGuard = {
+  beforeAddRow: async (defaultValue, insertIndex, count) => {
+    return new Promise((resolve) => {
+      console.log(defaultValue?.name, insertIndex, count);
+      setTimeout(() => resolve(true), 1000);
+    });
+  },
+  beforeRemoveRow: async (index, count) => {
+    const row = actionRef.current?.get(index as number);
+    console.log('--->', index, count, row);
+    return new Promise((resolve) => {
+      if (index === 0) {
+        resolve(false);
+        return;
+      }
+      setTimeout(() => resolve(true), 1000);
+    });
+  },
+};
+return (
+  <ProFormList actionGuard={actionGuard} actionRef={actionRef}>
+    <ProFormText key="useMode" name="name" label="姓名" />
+  </ProFormList>
+);
+```
+
+### actionRender 自定义操作按钮
+
+```tsx | pure
+  /**
+   * @name 自定义操作按钮
+   *
+   * @example 删除按钮
+   * actionRender:(field,action)=><a onClick={()=>action.remove(field.name)}>删除</a>
+   * @example 最多只能新增三行
+   * actionRender:(f,action,_,count)=><a onClick={()=>
+   *   count>2?alert("最多三行！"):action.add({id:"xx"})}>删除
+   * </a>
+   */
+  actionRender?: (
+    field: FormListFieldData,
+    /**
+     * 操作能力
+     * @example  action.add(data) 新增一行
+     * @example  action.remove(index) 删除一行
+     * @example  action.move(formIndex,targetIndex) 移动一行
+     */
+    action: FormListOperation,
+    /**
+     * 默认的操作dom
+     * [复制，删除]
+     */
+    defaultActionDom: ReactNode[],
+    /**
+     * 当前共有几个列表项
+     */
+    count: number,
+  ) => ReactNode[];
+
+
+```
+
+### ProFormList RenderProps 模式
+
+ProFormList 支持传入一个方法来获取到当前行的信息和快捷操作，这对于复杂的联动来说是很方便的。
+
+```tsx | pure
+<ProFormList>
+  {(
+    // 当前行的基本信息 {name: number; key: number}
+    meta,
+    // 当前的行号
+    index,
+    /**
+     * action
+     * @name 用于操作行的一些快捷方法
+     * @example 给第二行增加数据 action.add?.({},1);
+     * @example 删除第二行 action.remove?.(1);
+     * @example 从 1 移到 2: action.move?.(2,1);
+     * @example 获取当前行的数据: action.getCurrentRowData() -> {id:"xxx",name:'123',age:18}
+     * @example 设置当前行的数据: {id:"123",name:'123'} -> action.setCurrentRowData({name:'xxx'}) -> {id:"123",name:'xxx'}
+     * @example 清空当前行的数据：{id:"123",name:'123'} -> action.setCurrentRowData({name:undefined}) -> {id:"123"}
+     */
+    action,
+    // 总行数
+    count,
+  ) => {
+    return (
+      <div key="row">
+        <ProFormText name="id" />
+        <ProFormText name="name" />
+      </div>
+    );
+  }}
+</ProFormList>
+```
+
+这四个参数的类型定义如下：
+
+```tsx | pure
+type RenderActionParams = {
+  /**
+   * @name 当前行的meta信息
+   * @example {name: number; key: number}
+   */
+  meta: FormListFieldData;
+  /**
+   * @name 当前行的行号
+   */
+  index: number;
+  /**
+   * @name 用于操作行的一些快捷方法
+   * @example 给第二行增加数据 action.add?.({},1);
+   * @example 删除第二行 action.remove?.(1);
+   * @example 从 1 移到 2: action.move?.(2,1);
+   * @example 获取当前行的数据: action.getCurrentRowData() -> {id:"xxx",name:'123',age:18}
+   * @example 设置当前行的数据: {id:"123",name:'123'} -> action.setCurrentRowData({name:'xxx'}) -> {id:"123",name:'xxx'}
+   * @example 清空当前行的数据：{id:"123",name:'123'} -> action.setCurrentRowData({name:undefined}) -> {id:"123"}
+   */
+  action: FormListOperation & {
+    /**
+     * @name 获取当前行的数据
+     * @example getCurrentRowData -> {id:"xxx",name:'123',age:18}
+     */
+    getCurrentRowData: () => any;
+    /**
+     * @name 设置当前行的数据
+     * @example {id:"123",name:'123'} -> setCurrentRowData({name:'xxx'}) -> {id:"123",name:'123'}
+     * @example {id:"123",name:'123'} -> setCurrentRowData({name:undefined}) -> {id:"123"}
+     */
+    setCurrentRowData: (data: any) => void;
+  };
+  /**
+   * @name 总行数
+   */
+  count: number;
+};
+```
+
+## ProFormFieldSet
+
+ProFormFieldSet 可以将内部的多个 children 的值组合并且存储在 ProForm 中，并且可以通过 `transform` 在提交时转化。下面是一个简单的用法，可以方便的组合多个输入框，并且格式化为想要的数据。
+
+```tsx | pure
+<ProFormFieldSet
+  name="list"
+  label="组件列表"
+  // 支持 两种方式，type="group" 会用input.group 包裹
+  // 如果不配置 默认使用 space
+  type="group"
+  transform={(value: any) => ({ startTime: value[0], endTime: value[1] })}
+>
+  <ProFormText width="md" />
+  <ProFormText width="md" />
+  <ProFormText width="md" />
+</ProFormFieldSet>
+```
+
+## ProFormDependency
+
+ProFormDependency 是一个简化版本的 Form.Item，它默认内置了 noStyle 与 shouldUpdate，我们只需要配置 name 来确定我们依赖哪个数据，ProFormDependency 会自动处理 diff 和并且从表单中提取相应的值。
+
+name 参数必须要是一个数组，如果是嵌套的结构可以这样配置 `name={['name', ['name2', 'text']]}`。配置的 name 的值会在 renderProps 中传入。`name={['name', ['name2', 'text']]}` 传入的 values 的值 为 `{ name: string,name2: { text:string } }`。
+
+```tsx | pure
+<ProFormDependency name={['name']}>
+  {({ name }) => {
+    return (
+      <ProFormSelect
+        options={[
+          {
+            value: 'chapter',
+            label: '盖章后生效',
+          },
+        ]}
+        width="md"
+        name="useMode"
+        label={`与《${name}》合同约定生效方式`}
+      />
+    );
+  }}
+</ProFormDependency>
+```
+
+## 代码示例
+
+### 自定义删除和复制的 tooltip
+
+<code src="./demos/list-tooltip" title="ProForm.List" ></code>
+
+### 联动的 FormList
+
+<code src="./demos/base-use" title="ProForm.List" ></code>
+
+### 可调整的新建按钮位置
+
+<code src="./demos/list.tsx" title="ProForm.List-position" ></code>
+
+### 表单互相嵌套
+
+<code src="./demos/nested-list.tsx" title="ProForm.List-ProFormList" ></code>
+
+### 复杂联动
+
+<code src="./demos/dependency.tsx" title="ProForm.List-dependency" ></code>
+
+### 行为守卫
+
+<code src="./demos/pro-form-list.tsx" title="行为守卫"></code>
+
+### 增删条目限制
+
+<code src="./demos/countLimit.tsx" title="增删条目限制"></code>
+
+### 横向布局
+
+<code src="./demos/horizontal-layout.tsx" title="横向布局" ></code>