npm package: @quotalab/antd-form-builder
Description: VICS 연동을 위해 VICS에서 사용하는 Input 필드를 제한적으로 지원하는 폼 빌더이며, 앞으로 진행할 폼 빌더의 PoC 역할
Latest version: 2.2.56
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

# @quotalab/antd-form-builder

VICS 연동을 위해 VICS에서 사용하는 Input 필드를 제한적으로 지원하는 폼 빌더이며, 앞으로 진행할 폼 빌더의 PoC 역할

- **지원하는 컴포넌트 목록**

  ![Untitled](https://s3-us-west-2.amazonaws.com/secure.notion-static.com/236394a0-fc86-4941-8034-a77cf364f737/Untitled.png)


## 폼 빌더의 목적

폼 빌더의 목적은 폼 하나를 그리기 위해 디자이너와 프론트엔드 개발자 사이의 커뮤니케이션을 최소한으로 하기 위해 정형화된 폼을 그려내는 것입니다.

## 폼 빌더의 발전 방향

API의 유연성을 저해하지 않으면서 폼 필드와 레이아웃을 정의하는 것에 도움을 주는 방향으로 발전해야 합니다. 현재는 제한된 폼 필드만 사용할 수 있으며, 그 제한될 필드가 쿼타북 내의 폼을 녹여내지 못합니다.

### TODO

- 현재 Antd에 강하게 종속되어있습니다. 때문에 번들 사이즈가 매우 크며, Date 필드를 처리하기 위해 @quotalab/antd-datepicker 라이브러리를 사용하고 있어서 CommonJS 배포로 제한되고 있습니다.
- 현재 폼 빌더를 사용하기 위해서는 개발자가 피그마 화면을 직접 보고 meta 필드를 직접 입력해야 합니다. 또한, 디자이너 역시 그리고 싶은 폼의 형태를 구상한 후, 피그마의 컴포넌트로 하나씩 그려야합니다. 이 과정을 최소화하기 위해 Drag&Drop 으로 디자이너가 폼을 그리면 이에 상응하는 JSON 파일을 출력하고 Figma로 볼 수 있도록 하는 작업이 필요합니다.

## FormBuilder API

다음은 폼 빌더를 이루는 필드의 사용 예시입니다.

### FormBuilder props

|  Name | Type | Description |
| --- | --- | --- |
| meta | MetaFieldItem[] | 폼 빌더의 메타 정보를 이루는 props입니다. |

### MetaFieldItem Type

`MetaFieldItem` 타입은 폼 빌더의 각 행을 이루는 필드입니다.

|  Name | Type | Description                                                                                                                                         |
| --- | --- |-----------------------------------------------------------------------------------------------------------------------------------------------------|
| name | string | Antd FormItem의 name에 대입되는 값입니다.                                                                                                                     |
| label | undefined or string | Antd FormItem의 label에 대입되는 값입니다.                                                                                                                    |
| rules | undefined or Rule[] | Antd FormItem의 rules에 대입되는 값입니다.                                                                                                                    |
| required | undefined or boolean or BaseFieldOptionalInteractiveCallback | 해당 값이 true로 반환된다면 Antd는 해당 값을 필수 필드로 지정합니다. <br />BaseFieldOptionalInteractiveCallback 함수의 인자로 전달되는 safeGetFieldValue를 이용해 폼의 상태를 즉각적으로 받아올 수 있습니다. |
| disabled | undefined or boolean or BaseFieldOptionalInteractiveCallback | 해당 값이 true로 반환된다면 Antd는 해당 값을 비활성 필드로 지정합니다. <br />BaseFieldOptionalInteractiveCallback 함수의 인자로 전달되는 safeGetFieldValue를 이용해 폼의 상태를 즉각적으로 받아올 수 있습니다.      |
| component | keyof BaseFieldComponentProps | 어떤 컴포넌트를 렌더링할 것인지 결정하는 값입니다. 해당 값에 따라 MetaFieldItem 타입이 확장되거나 제한됩니다.                                                                                |
| props | ComponentProps<keyof BaseFieldComponentProps> | component로 전달되는 props 값입니다.                                                                                                                         |

### BaseFieldOptionalInteractiveCallback Type

required / disabled 필드에서 지정할 수 있는 타입입니다.

```tsx
type BaseFieldOptionalInteractiveCallback = (args: {
  safeGetFieldValue: typeof safeGetFieldValueFunction;
}) => boolean;
```

### BaseFieldComponentProps Type

|  Name | Props Type | Description                                                                                                    |
| --- | --- |----------------------------------------------------------------------------------------------------------------|
| text | ComponentProps<typeof Input> | 특수문자를 포함하여 모든 문자를 입력할 수 있습니다. <br />입력한 값은 string으로 저장합니다.                                                     |
| textarea | ComponentProps<typeof Input.TextArea> | 특수문자를 포함하여 모든 문자를 입력할 수 있습니다. <br />입력한 값은 string으로 저장합니다.                                                     |
| select | SelectProps<string or string[]> | 지정된 option 중 하나를 선택합니다. <br />필드에 string을 입력하면 일치하는 option을 검색할 수 있습니다. <br />선택된 값은 각 option에 설정한 형식으로 저장합니다. |
| boolean | RadioGroupProps | 상호 배타적인 false, true 중 하나를 선택할 수 있습니다. <br />선택한 값은 false 또는 true로 저장합니다.                                       |
| number | InputNumberProps | 음수 및 소수점을 포함한 숫자를 입력할 수 있습니다. <br />입력한 값은 number로 저장합니다.                                                      |
| date | ComponentProps<typeof DatePicker> | datepicker에서 연, 월, 일을 선택할 수 있습니다. <br />선택한 값은 date로 저장합니다.                                                    |
| formList | FormListProps | index, element에 따라 contentsBox 내부에 formBuilder를 출력합니다. <br />addButton을 통해 arrayItem을 생성하고 삭제할 수 있습니다.               |
| custom | never | 개발자가 직접 필요한 폼의 필드를 ReactElement 타입으로 전달할 수 있습니다.                                                               |

### BaseFieldComponentProps MetaFieldItem Type

BaseFieldComponentProps에 따라서 변화하는  MetaFieldItem 타입입니다.

| Component Name             | MetaField | Props Type | Description                                                                                    |
|----------------------------| --- | --- |------------------------------------------------------------------------------------------------|
| select                     | options | Array<{ label: string; value: string }> | Select에서 선택할 수 있는 option 리스트를 입력합니다.                                                           |
|                            | multiple | undefined or boolean | true로 지정될 경우, 여러 option을 선택할 수 있습니다.                                                           |
| number                     | type | undefined or ‘default’ or ‘amount’ or ‘percent’ | ‘amount’로 지정될 경우, suffix로 currency symbol을 노출합니다. <br />’percent’로 지정될 경우, prefix로 ‘%’를 노출합니다. |
| number <br />‘amount’ type | currency | CurrencySymbol | suffix로 노출할 currency 값을 입력합니다.                                                                 |
| date                       | showTime | undefined or boolean | HH:mm 값을 입력받는 필드를 함께 노출합니다.                                                                    |
| custom                     | customComponent | (field: BaseFieldProps<'custom'>) => ReactElement | ReactElement 값을 render props 형태로 전달합니다.                                                        |
|                            | disabled | undefined or never | custom 값은 disabled 필드를 meta 정보에 입력할 필요가 없습니다. <br />렌더링할 컴포넌트에 직접 입력해주세요.                            |
| formList                   | disabled | undefined or never | FormList 컴포넌트는 disabled 상태로 지정될 수 없습니다.                                                        |