npm package: @n3/react-form-kit-migrate
Description: Fields for @n3/react-form-builder styled with @n3/kit
Author: Vadim Taits
Latest version: 0.1.2

# @n3/react-form-kit

Поля для `@n3/react-form-builder`, стилизованные с помощью `@n3/kit`

## Использование

### Форма создания/редактирования

```
import { Form } from '@n3/react-form-builder';
import { createFields } from '@n3/react-form-kit';

const fieldTypes = createFields(options);

const getFieldType = ({ type }) => fieldTypes[type];

...

<Form
  {...otherFormProps}
  getFieldType={getFieldType}
/>
```

`options` - необязательное, объект, может содержать параметры:

- `get` - асинхронная функция get-запроса на сервер, принимает аргументы:

  - `url` - строка;

  - `queryParams` - объект параметров.

### Форма просмотра

```
import { Form } from '@n3/react-form-builder';
import { createShowFields } from '@n3/react-form-kit';

const showFieldTypes = createShowFields();

const getShowFieldType = ({ type }) => showFieldTypes[type];

...

<Form
  {...otherFormProps}
  getFieldType={getShowFieldType}
/>
```

### Кастомное поле для формы создания/редактирования

Создаёт поле с выводом заголовка, ошибок, ворнингов, звёздочек в случае обязательности

```
import { FieldWrapper } from '@n3/react-form-kit';

const FieldComponent = (props) => {
  ...

  return (
    <FieldWrapper
      {...props}
    >
      {({
        input,
        meta,
        disabled,
        hasError,
        hasWarning,
      }) => {
        ...
      }}
    </FieldWrapper>
  );
};
```

### Кастомное поле для формы просмотра

Создаёт поле с выводом заголовка, ошибок и ворнингов

```
import { ShowFieldWrapper } from '@n3/react-form-kit';

const FieldComponent = (props) => {
  ...

  return (
    <ShowFieldWrapper
      {...props}
    >
      {({
        input,
        meta,
        disabled,
        hasError,
        hasWarning,
      }) => {
        ...
      }}
    </ShowFieldWrapper>
  );
};
```

## Схема полей

Каждое поле, созданное при помощи `createField` или `createShowField` иммеет следующие необязательные параметры:

- `label` - строка, заголовок поля;

- `onlyField` - булево, если true, заголовок поля не отображается;

- `required` - булево, если true, на форме создания/редактирования рядом с заголовком отображается `*`;

- `help_text` - строка, подсказка поля;

- `initial` - значение поля по умолчанию;

- `labelCols` - число, количество колонок, которое занимает заголовок поля, по умолчанию 3;
- `fieldCols` - число, количество колонок, которое занимает поле, по умолчанию 5.

### Реализованные поля

#### string

Поле ввода текста. Параметры:

- `inputComponent` - react-компонент, компонент поля, по умолчанию `input`;

- `inputType` - строка, тип инпута, по умолчанию `text`;

- `debounceTimeout` - задержка debounce-инпута, по умолчанию `300`;

- `max_length` - число, максимальное количество введённых символов;

- `mask` - маска формата [react-input-mask](https://www.npmjs.com/package/react-input-mask), если задано, параметры `debounceTimeout` и `max_length` не работают;

- `disabled` - булево;

- `read_only` - булево;

- `placeholder` - строка.

#### url

Полностью аналогично `string`.

#### choice

Селект. Параметры:

- `choices` - массив объектов опций селекта, по умолчанию имеют формат `{ value, display_name }`, где `value` - значение, отправляемое на сервер, `label` - текст для отображения опции;

- `valueKey` - ключ значения опции для отправки на сервер, по умолчанию `value`;

- `labelKey` - ключ значения опции для отображения, по умолчанию `display_name`;

- `disabled` - булево;

- `read_only` - булево.

#### multiple_choice

Мультиселект. Аналогичен `choice`, но принимает и отправляет массивы значений.

#### ajax_choice

Селект с подгрузкой опций с сервера. Использует компонент `SelectAjax`. Параметры:

- `choices_url` - строка, url для запроса данных, ответ сервера должен быть в стандартном drf-формате (`{ results, next }`);

- `queryParams` - объект параметров запроса, не зависящих от других полей;

- `debounceTimeout` - задержка перед запросом в мс, по умолчанию `300`;

- `choices_cascade_params` - объект, ключами которого являются имена других полей, а значениями - названия параметров, под которыми они будут переданы на сервер;

- `isClearOnChange`- булево, сбросить ли значение поля при изменении зависимостей;

- `parseValue` - необязательное, функция загрузки опции по id. По умолчанию делается запрос на `<choices_url><id>/` с параметрами `queryParams`. Принимает аргументы;

  1. `get` - из параметров `createFields`;

  2. `value` - id опции;

  3. `choicesUrl`

  4. `queryParams`

  5. `mapResponseSimple` - смотри ниже;

- `mapResponseSimple` - необязательное, функция маппинга загруженного значения при парсинге в опцию.

#### ajax_multiple_choice

Мультиселект с подгрузкой опций с сервера. Аналогичен `ajax_choice`, но принимает и отправляет массивы значений.

#### date

Дейтпикер. Принимает значения в формате js-объекта `Date`, строки формата `2018-12-26` или строки формата `2018-10-14T22:33:20`. Параметры:

- `disabled` - булево;

- `read_only` - булево.

#### datetime

Дейттаймпикер. Принимает значения в формате js-объекта `Date` или строки формата `2018-10-14T22:33:20`. Параметры:

- `disabled` - булево;

- `read_only` - булево.

#### boolean

Чекбокс. Принимает булевы значения. Параметры:

- `disabled` - булево;

- `falsyLabel` - строка, используется для вывода ложного значения на форме просмотра;

- `truthyLabel` - строка, используется для вывода истинного значения на форме просмотра.

#### dynamic

Поле со схемой, зависящей от других полей. Пример:

```javascript
const schema = {
  type: 'dynamic',

  getSchema: ({
    otherField,
  }, phase) => ({
    type: 'string',
    label: 'Поле',
    required: Boolean(otherField),
  }),
};
```

Параметры:

- `getSchema` - обязательное, функция, первым аргументом принимает объект значений формы. Должна вернуть схему поля для рендера или `null`. В случае возврата `null` поле не отображается и не участвует в сериализации и парсинге значений формы, а также сборе ошибок. Аргументы:

  1. `values` - объект значений формы на этапе рендера/сериализации или объект необработанных значений на этапе парсинга;

  2. `phase` - текущая фаза [@vtaits/form-schema](https://www.npmjs.com/package/@vtaits/form-schema). Принимает значения: `'parse'`, `'serialize'`, `'render'`;

  3. `getFieldSchema` - смотри [@n3/react-form-builder](https://www.npmjs.com/package/@n3/react-form-builder);

  4. `getFieldType` - смотри [@n3/react-form-builder](https://www.npmjs.com/package/@n3/react-form-builder).

### Рендер ошибок и ворнингов

Выводит компонент `Alert` из `@n3/kit`.

```
import { Form } from '@n3/react-form-builder';
import { renderError, renderWarning } from '@n3/react-form-kit';

<Form
  {...otherFormProps}
  renderError={renderError}
  renderWarning={renderWarning}
/>
```

Поддерживают следующие форматы ошибки/ворнинга:

- строка
- массив строк
- массив объектов вида `{ message }`, где `message` - строка
- объект вида `{ title, messages }`, где `title` - строка, `messages` - массив строк или массив объектов вида `{ message }`, где `message` - строка

### Конфигурация через FormConfigContext

```typescript
<FormConfigContext.Provider
  value={{
    labelCols: 4,
    fieldCols: 8,
    onFieldChange: (value, prevValue, name, form) => {
      // ...
    },
  }}
>
  {/** ... */}
</FormConfigContext.Provider>
```

- `labelCols` - обязательное, число, количество колонок заголовков по умолчанию;
- `fieldCols` - обязательное, число, количество колонок полей по умолчанию;
- `onFieldChange` - необязательное, функция, глобальный обработчик изменений значений полей.