@reformer/core 1.0.0-beta.1

package/dist/core/behavior/behaviors/watch-field.d.ts

@@ -0,0 +1,80 @@
+import { FieldPathNode } from '../../types';
+import { BehaviorContext, WatchFieldOptions } from '../types';
+/**
+ * Выполняет callback при изменении поля
+ *
+ * @group Behaviors
+ * @category Behavior Rules
+ *
+ * @param field - Поле для отслеживания
+ * @param callback - Функция обратного вызова
+ * @param options - Опции (`debounce`, `immediate`)
+ *
+ * @example Async loader with try/catch + guard + debounce
+ * ```typescript
+ * import { watchField, type BehaviorSchemaFn } from '@reformer/core/behaviors';
+ *
+ * interface AddressForm { region: string; city: string }
+ *
+ * export const addressBehavior: BehaviorSchemaFn<AddressForm> = (path) => {
+ *   watchField(
+ *     path.region,
+ *     async (region, ctx) => {
+ *       if (!region) {
+ *         ctx.form.city.updateComponentProps({ options: [] });
+ *         return; // guard: пустое значение не триггерит fetch
+ *       }
+ *       try {
+ *         const { data: cities } = await fetchCities(region);
+ *         ctx.form.city.updateComponentProps({ options: cities });
+ *       } catch (error) {
+ *         console.error('[addressBehavior] failed to load cities:', error);
+ *         ctx.form.city.updateComponentProps({ options: [] });
+ *       }
+ *     },
+ *     { immediate: false, debounce: 300 }, // обязательные опции для async
+ *   );
+ * };
+ * ```
+ *
+ * @example Sync handler с консолидацией нескольких зависимостей в один watcher
+ * ```typescript
+ * import { watchField, type BehaviorSchemaFn } from '@reformer/core/behaviors';
+ *
+ * interface InsuranceForm {
+ *   insuranceType: 'casco' | 'osago' | 'property' | '';
+ *   vehicleVin: string;
+ *   propertyType: string;
+ * }
+ *
+ * export const insuranceBehavior: BehaviorSchemaFn<InsuranceForm> = (path) => {
+ *   // ОДИН watchField на trigger-поле — несколько watcher'ов на одно поле = "Cycle detected"
+ *   watchField(
+ *     path.insuranceType,
+ *     (type, ctx) => {
+ *       const isVehicle = type === 'casco' || type === 'osago';
+ *       const isProperty = type === 'property';
+ *
+ *       // Guard — ставим только если состояние реально меняется
+ *       if (isVehicle) {
+ *         if (ctx.form.vehicleVin.disabled.value) ctx.form.vehicleVin.enable();
+ *       } else {
+ *         if (!ctx.form.vehicleVin.disabled.value) ctx.form.vehicleVin.disable();
+ *         if (ctx.form.vehicleVin.getValue() !== '') ctx.form.vehicleVin.setValue('');
+ *       }
+ *
+ *       if (isProperty) {
+ *         if (ctx.form.propertyType.disabled.value) ctx.form.propertyType.enable();
+ *       } else {
+ *         if (!ctx.form.propertyType.disabled.value) ctx.form.propertyType.disable();
+ *         if (ctx.form.propertyType.getValue() !== '') ctx.form.propertyType.setValue('');
+ *       }
+ *     },
+ *     { immediate: false }, // CRITICAL: предотвращает запуск во время инициализации
+ *   );
+ * };
+ * ```
+ *
+ * @see [docs/llms/22-cycle-detection.md](../../../../docs/llms/22-cycle-detection.md)
+ */
+export declare function watchField<TForm, TField>(field: FieldPathNode<TForm, TField>, callback: (value: TField, ctx: BehaviorContext<TForm>) => void | Promise<void>, options?: WatchFieldOptions): void;

package/dist/core/behavior/compose-behavior.d.ts

@@ -0,0 +1,96 @@
+import { FieldPath, FieldPathNode, FormFields, FormValue } from '../types';
+import { BehaviorSchemaFn } from './types';
+/**
+ * Преобразовать FieldPath во вложенный путь для композиции behavior схем
+ *
+ * Аналог toFieldPath из validation API.
+ *
+ * @param fieldPath - Поле для преобразования
+ * @returns Вложенный FieldPath
+ *
+ * @example
+ * ```typescript
+ * // address-behavior.ts
+ * export const addressBehavior = (path: FieldPath<Address>) => {
+ *   watchField(path.country, async (country, ctx) => {
+ *     const regions = await fetchRegions(country);
+ *     ctx.updateComponentProps(path.region, { options: regions });
+ *   });
+ * };
+ *
+ * // user-behavior.ts
+ * export const userBehavior = (path: FieldPath<User>) => {
+ *   // Композиция: применяем addressBehavior к вложенному полю
+ *   addressBehavior(toBehaviorFieldPath(path.address));
+ * };
+ * ```
+ */
+export declare function toBehaviorFieldPath<TForm, TField>(fieldPath: FieldPathNode<TForm, TField> | undefined): FieldPath<TField>;
+/**
+ * Применить behavior схему к вложенному полю или полям
+ *
+ * Поддерживает:
+ * - Одно поле или массив полей
+ * - Одну схему или массив схем
+ * - Все комбинации (поле + схема, поле + схемы, поля + схема, поля + схемы)
+ *
+ * @param fields - Одно поле или массив полей
+ * @param behaviors - Одна схема или массив схем
+ *
+ * @example
+ * ```typescript
+ * // Одна схема к одному полю
+ * apply(path.registrationAddress, addressBehavior);
+ *
+ * // Одна схема к нескольким полям
+ * apply([path.registrationAddress, path.residenceAddress], addressBehavior);
+ *
+ * // Несколько схем к одному полю
+ * apply(path.properties, [propertyBehavior, arrayBehavior]);
+ *
+ * // Несколько схем к нескольким полям
+ * apply(
+ *   [path.registrationAddress, path.residenceAddress],
+ *   [addressBehavior, validationBehavior]
+ * );
+ * ```
+ */
+export declare function apply<TForm, TField>(fields: FieldPathNode<TForm, TField> | Array<FieldPathNode<TForm, TField> | undefined> | undefined, behaviors: BehaviorSchemaFn<TField> | Array<BehaviorSchemaFn<TField>>): void;
+/**
+ * Условное применение behavior схем (аналог applyWhen из validation API)
+ *
+ * ⚠️ ВАЖНО: Эта функция НЕ создаёт новые behaviors при каждом изменении условия!
+ * Вместо этого behaviors регистрируются ОДИН РАЗ при первом вызове и затем
+ * просто не выполняются, если условие не выполнено.
+ *
+ * Это отличается от старой реализации, которая создавала утечку памяти,
+ * регистрируя behaviors при каждом изменении conditionField.
+ *
+ * @param conditionField - Поле для проверки условия
+ * @param condition - Функция проверки условия
+ * @param callback - Callback для применения behavior схем
+ *
+ * @example
+ * ```typescript
+ * // Применить addressBehavior только когда sameAsRegistration === false
+ * applyWhen(
+ *   path.sameAsRegistration,
+ *   (value) => value === false,
+ *   (path) => {
+ *     apply(path.residenceAddress, addressBehavior);
+ *   }
+ * );
+ *
+ * // Или с прямым использованием path
+ * applyWhen(
+ *   path.hasProperty,
+ *   (value) => value === true,
+ *   (path) => {
+ *     apply(path.properties, propertyBehavior);
+ *     // Можно применить несколько схем
+ *     apply([path.properties, path.items], arrayBehavior);
+ *   }
+ * );
+ * ```
+ */
+export declare function applyWhen<TForm extends FormFields, TValue extends FormValue>(conditionField: FieldPathNode<TForm, TValue> | undefined, condition: (value: TValue) => boolean, callback: (path: FieldPath<TForm>) => void): void;

package/dist/core/behavior/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Behavior Schema API - Декларативное описание реактивного поведения форм
+ *
+ * @group Behaviors
+ * @module behaviors
+ */
+export type { BehaviorSchemaFn, BehaviorContext, BehaviorHandlerFn, BehaviorOptions, CopyFromOptions, EnableWhenOptions, ComputeFromOptions, WatchFieldOptions, RevalidateWhenOptions, SyncFieldsOptions, } from './types';
+export * from './behaviors';
+export { apply, applyWhen, toBehaviorFieldPath } from './compose-behavior';
+export { BehaviorRegistry } from './behavior-registry';
+export { BehaviorContextImpl } from './behavior-context';

package/dist/core/behavior/types.d.ts

@@ -0,0 +1,146 @@
+import { GroupNode } from '../nodes/group-node';
+import { FieldPath } from '../types/field-path';
+import { FormContext } from '../types/form-context';
+/**
+ * Тип функции behavior схемы
+ * Принимает FieldPath и описывает поведение формы
+ *
+ * @group Behaviors
+ * @category Behavior Types
+ */
+export type BehaviorSchemaFn<T> = (path: FieldPath<T>) => void;
+/**
+ * Контекст для behavior callback функций
+ * Алиас для FormContext
+ *
+ * @group Behaviors
+ * @category Behavior Types
+ *
+ * @example
+ * ```typescript
+ * watchField(path.country, async (country, ctx) => {
+ *   // Прямой типизированный доступ к полям
+ *   const cities = await fetchCities(country);
+ *   ctx.form.city.updateComponentProps({ options: cities });
+ *
+ *   // Безопасная установка значения (без циклов)
+ *   ctx.setFieldValue('city', null);
+ * });
+ * ```
+ */
+export type BehaviorContext<TForm> = FormContext<TForm>;
+/**
+ * Функция-handler для behavior
+ *
+ * Создает effect подписку для реактивного поведения формы.
+ *
+ * @group Behaviors
+ * @category Behavior Types
+ *
+ * @template TForm - Тип формы
+ * @param form - Корневой узел формы (GroupNode)
+ * @param context - Контекст для работы с формой
+ * @param withDebounce - Функция-обертка для debounce
+ * @returns Функция cleanup для отписки от effect или null
+ *
+ * @example
+ * ```typescript
+ * const handler: BehaviorHandlerFn<MyForm> = (form, context, withDebounce) => {
+ *   const sourceNode = form.getFieldByPath('email');
+ *
+ *   return effect(() => {
+ *     const value = sourceNode.value.value;
+ *     withDebounce(() => {
+ *       // Логика behavior
+ *     });
+ *   });
+ * };
+ * ```
+ */
+export type BehaviorHandlerFn<TForm> = (form: GroupNode<TForm>, context: BehaviorContext<TForm>, withDebounce: (callback: () => void) => void) => (() => void) | null;
+/**
+ * Общие опции для behavior
+ *
+ * @group Behaviors
+ * @category Behavior Types
+ */
+export interface BehaviorOptions {
+    /** Debounce в миллисекундах */
+    debounce?: number;
+}
+/**
+ * Опции для copyFrom
+ *
+ * @group Behaviors
+ * @category Behavior Types
+ */
+export interface CopyFromOptions<TSource, TForm = unknown> {
+    /** Условие копирования */
+    when?: (form: TForm) => boolean;
+    /** Какие поля копировать (для групп) */
+    fields?: (keyof TSource)[] | 'all';
+    /** Трансформация значения */
+    transform?: (value: TSource) => unknown;
+    /** Debounce в мс */
+    debounce?: number;
+}
+/**
+ * Опции для enableWhen/disableWhen
+ *
+ * @group Behaviors
+ * @category Behavior Types
+ */
+export interface EnableWhenOptions {
+    /** Сбросить значение при disable */
+    resetOnDisable?: boolean;
+    /** Debounce в мс */
+    debounce?: number;
+}
+/**
+ * Опции для computeFrom
+ *
+ * @group Behaviors
+ * @category Behavior Types
+ */
+export interface ComputeFromOptions<TForm> {
+    /** Когда вычислять */
+    trigger?: 'change' | 'blur';
+    /** Debounce в мс */
+    debounce?: number;
+    /** Условие применения */
+    condition?: (form: TForm) => boolean;
+}
+/**
+ * Опции для watchField
+ *
+ * @group Behaviors
+ * @category Behavior Types
+ */
+export interface WatchFieldOptions {
+    /** Debounce в мс */
+    debounce?: number;
+    /** Вызвать сразу при инициализации */
+    immediate?: boolean;
+}
+/**
+ * Опции для revalidateWhen
+ *
+ * @group Behaviors
+ * @category Behavior Types
+ */
+export interface RevalidateWhenOptions {
+    /** Debounce в мс */
+    debounce?: number;
+}
+/**
+ * Опции для syncFields
+ *
+ * @group Behaviors
+ * @category Behavior Types
+ */
+export interface SyncFieldsOptions<T> {
+    /** Трансформация значения */
+    transform?: (value: T) => T;
+    /** Debounce в мс */
+    debounce?: number;
+}

package/dist/core/factories/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Фабрики для создания узлов формы
+ *
+ * Централизованное место для всех фабрик и builder-паттернов.
+ */
+export { NodeFactory } from './node-factory';

package/dist/core/factories/node-factory.d.ts

@@ -0,0 +1,186 @@
+import { FormNode } from '../nodes/form-node';
+/**
+ * Фабрика для создания узлов формы.
+ *
+ * Определяет тип конфига и создаёт соответствующий узел (FieldNode, GroupNode, ArrayNode).
+ * Используется внутри `getReformerForm`/`group`/`array` — явно вызывать обычно не нужно.
+ *
+ * @example
+ * ```typescript
+ * import { NodeFactory } from '@reformer/core';
+ *
+ * const node = NodeFactory.create({ value: '' }); // → FieldNode<string>
+ * ```
+ */
+export declare class NodeFactory {
+    /**
+     * Создает узел формы на основе конфигурации
+     *
+     * ✅ ОБНОВЛЕНО: Теперь поддерживает массивы напрямую
+     *
+     * Автоматически определяет тип узла:
+     * - FieldNode: имеет value и component
+     * - ArrayNode: массив [schema, ...items] или { schema, initialItems }
+     * - GroupNode: объект без value, component, schema
+     *
+     * @param config Конфигурация узла
+     * @returns Экземпляр FieldNode, GroupNode или ArrayNode
+     * @throws Error если конфиг не соответствует ни одному типу
+     *
+     * @example
+     * ```typescript
+     * const factory = new NodeFactory();
+     *
+     * // FieldNode
+     * const field = factory.createNode({
+     *   value: 'test@mail.com',
+     *   component: Input,
+     *   validators: [required, email]
+     * });
+     *
+     * // GroupNode
+     * const group = factory.createNode({
+     *   email: { value: '', component: Input },
+     *   password: { value: '', component: Input }
+     * });
+     *
+     * // ArrayNode (объект)
+     * const array = factory.createNode({
+     *   schema: { title: { value: '', component: Input } },
+     *   initialItems: [{ title: 'Item 1' }]
+     * });
+     *
+     * // ArrayNode (массив) - новый формат
+     * const array2 = factory.createNode([
+     *   { title: { value: '', component: Input } }, // schema
+     *   { title: 'Item 1' }, // initial item 1
+     *   { title: 'Item 2' }  // initial item 2
+     * ]);
+     * ```
+     */
+    createNode<T>(config: unknown): FormNode<T>;
+    /**
+     * Создать ArrayNode из массива [schema, ...initialItems]
+     *
+     * ✅ НОВОЕ: Извлечено из GroupNode для централизации логики
+     *
+     * Формат: [itemSchema, ...initialItems]
+     * - Первый элемент - схема элемента массива
+     * - Остальные элементы - начальные значения
+     *
+     * @param config Массив с схемой и начальными элементами
+     * @returns ArrayNode
+     *
+     * @example
+     * ```typescript
+     * const factory = new NodeFactory();
+     *
+     * // Массив с начальными элементами
+     * const array = factory.createArrayNodeFromArray([
+     *   { title: { value: '', component: Input } }, // schema
+     *   { title: 'Item 1' }, // initial value
+     *   { title: 'Item 2' }  // initial value
+     * ]);
+     * ```
+     * @private
+     */
+    private createArrayNodeFromArray;
+    /**
+     * Извлечь значения из схемы (рекурсивно)
+     *
+     * ✅ НОВОЕ: Извлечено из GroupNode для централизации логики
+     *
+     * Преобразует схему формы в объект со значениями:
+     * - `{ name: { value: 'John', component: Input } } → { name: 'John' }`
+     * - Поддерживает вложенные группы
+     * - Поддерживает массивы
+     *
+     * @param schema Схема формы
+     * @returns Объект со значениями полей
+     *
+     * @example
+     * ```typescript
+     * const factory = new NodeFactory();
+     *
+     * const schema = {
+     *   name: { value: 'John', component: Input },
+     *   age: { value: 30, component: Input },
+     *   address: {
+     *     city: { value: 'Moscow', component: Input }
+     *   }
+     * };
+     *
+     * factory.extractValues(schema);
+     * // { name: 'John', age: 30, address: { city: 'Moscow' } }
+     * ```
+     */
+    extractValues(schema: unknown): unknown;
+    /**
+     * Проверяет, является ли конфиг конфигурацией поля (FieldConfig)
+     *
+     * FieldConfig имеет обязательные свойства:
+     * - value: начальное значение поля
+     * - component: React-компонент для отображения
+     *
+     * @param config Проверяемая конфигурация
+     * @returns true если config является FieldConfig
+     *
+     * @example
+     * ```typescript
+     * const factory = new NodeFactory();
+     *
+     * factory.isFieldConfig({ value: '', component: Input }); // true
+     * factory.isFieldConfig({ email: { value: '' } }); // false
+     * factory.isFieldConfig(null); // false
+     * ```
+     */
+    isFieldConfig(config: unknown): boolean;
+    /**
+     * Проверяет, является ли конфиг конфигурацией массива (ArrayConfig)
+     *
+     * ArrayConfig имеет обязательное свойство:
+     * - schema: схема для элементов массива
+     *
+     * И НЕ имеет:
+     * - value (отличие от FieldConfig)
+     *
+     * @param config Проверяемая конфигурация
+     * @returns true если config является ArrayConfig
+     *
+     * @example
+     * ```typescript
+     * const factory = new NodeFactory();
+     *
+     * factory.isArrayConfig({ schema: {}, initialItems: [] }); // true
+     * factory.isArrayConfig({ value: '', component: Input }); // false
+     * factory.isArrayConfig({ email: { value: '' } }); // false
+     * ```
+     */
+    isArrayConfig(config: unknown): boolean;
+    /**
+     * Проверяет, является ли конфиг конфигурацией группы (GroupConfig)
+     *
+     * GroupConfig - это объект, который:
+     * - НЕ является FieldConfig (нет value/component)
+     * - НЕ является ArrayConfig (нет schema)
+     * - Содержит вложенные конфиги полей/групп/массивов
+     *
+     * @param config Проверяемая конфигурация
+     * @returns true если config является GroupConfig
+     *
+     * @example
+     * ```typescript
+     * const factory = new NodeFactory();
+     *
+     * factory.isGroupConfig({
+     *   email: { value: '', component: Input },
+     *   password: { value: '', component: Input }
+     * }); // true
+     *
+     * factory.isGroupConfig({ value: '', component: Input }); // false
+     * factory.isGroupConfig({ schema: {} }); // false
+     * factory.isGroupConfig(null); // false
+     * ```
+     */
+    isGroupConfig(config: unknown): boolean;
+}