Skip to main content

Введение

ReFormer — библиотека для построения сложных форм на React, основанная на сигналах. Она даёт декларативный способ описывать формы с валидацией, вычисляемыми полями и условной логикой — без ручной синхронизации состояния и лишних перерисовок. Ядро от React не зависит: привязка к React — отдельный вход @reformer/core/react.

Философия: архитектура M1​

В основе ядра лежит архитектура M1, разделяющая форму на четыре слоя. Каждый слой отвечает за одну задачу, что делает форму предсказуемой, переиспользуемой и легко тестируемой.

Модель  ─────►  Схема  ─────►  Форма  ─────►  Behavior
createModel     привязка       createForm     defineFormBehavior
значения        поле↔сигнал    ноды формы     реактивная логика
  1. Модель (createModel) — источник истины для значений. Обычный на вид объект, где под каждым полем стоит реактивный сигнал. Значения принадлежат модели, а не UI.
  2. Схема — дерево узлов: узел поля привязывает поле модели к компоненту ({ model: model.$.field, component, componentProps }), контейнер собирает узлы в children. Правил валидации в схеме нет — они живут отдельной схемой defineValidation.
  3. Форма (createForm) — собирает всё одним вызовом: строит ноды (FormControl / FormGroup / FormArray) поверх сигналов модели, подключает правила валидации, поток шагов и поведение. К полям обращаются через типизированную группу: form.email, form.address.city.
  4. Behavior (defineFormBehavior) — декларативная реактивная логика: вычисляемые поля, условная доступность, синхронизация, реакции на изменения.

Такое разделение — ключевая идея: «какие данные собираем» (модель + схема) отделено от «как данные реагируют» (behavior) и от «правильны ли данные» (схема валидации).

Ключевые возможности​

  • Реактивность на сигналах — точечные обновления без лишних ре-рендеров.
  • Типобезопасность — полный вывод типов из формы; доступ к полям через типизированную группу FormGroup.
  • Декларативная валидация — набор встроенных валидаторов-фабрик + произвольная кастомная логика; правило возвращает код замечания, а текст даёт словарь сообщений.
  • Декларативные behaviors — вычисляемые поля, условная доступность, синхронизация полей.
  • Вложенность и массивы — сложные структуры и динамические списки, принадлежащие модели.
  • Пошаговые формы — поток шагов с правилами каждого шага прямо в сборке формы.
  • AI-friendly — предсказуемый API с чёткими паттернами, удобный для генерации ассистентами.

Экосистема​

@reformer/core — фундамент. Поверх него:

ПакетНазначение
@reformer/coreядро: модель, схема, форма, behaviors, валидаторы, хуки
@reformer/cdkheadless-компоненты (FieldArray, FormWizard, FormField)
@reformer/ui-kitготовые стилизованные поля (Input, Select, Checkbox, …)
@reformer/renderer-reactрендеринг формы по дереву схемы
@reformer/renderer-jsonформа из JSON-описания
@reformer/mcpMCP-сервер для AI-ассистентов

Что внутри @reformer/core​

Пакет разбит на слои, у каждого свой вход:

СлойИмпортНазначение
Модель@reformer/corecreateModel, arrayOf — источник истины значений; доступ к сигналам через model.$.<field>
Форма и ноды@reformer/corecreateForm — сборка одним вызовом; ноды FormControl / FormGroup / FormArray; доступ к полям через form.<field>
Валидация@reformer/core/validationсхема defineValidation + операторы validate, validateAsync, validateWhen, apply, applyEach; раннер validateModel
Валидаторы@reformer/core/validatorsчистые фабрики required, email, min, max, minLength, pattern, phone, url, числовые, датовые и файловые
Сообщения@reformer/core/i18nсловарь текстов замечаний defineIssueMessages, резолвер resolveIssueMessage, локали
Behaviors@reformer/core/behaviorsдекларативный DSL defineFormBehavior + операторы compute, onChange, enableWhen, copyFrom, …
Signals@reformer/core/signalsединый реактивный рантайм (signal, computed, effect, batch) для интеграций

React-часть (@reformer/core/react): useFormBundle (стабильная сборка формы), useFormControl (полное состояние поля), useFormControlValue (значение T напрямую), useArrayLength (реактивная длина массива), useFormFlow (состояние потока шагов), I18nProvider и useIssueMessage (язык и тексты замечаний).

Дальше​