@reformer/core 1.1.0 → 2.0.0-beta.11

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

@@ -1,21 +1,25 @@
+import { GroupNode } from '../nodes/group-node';
+import { BehaviorHandlerFn, BehaviorOptions } from './types';
+import { AbstractRegistry } from '../utils/abstract-registry';
+import { FormFields } from '../types';
 /**
- * BehaviorRegistry - регистрация и управление behavior схемами
- *
- * Аналогично ValidationRegistry, но для реактивного поведения форм
+ * Зарегистрированный behavior с опциями
  */
-import type { GroupNode } from '../nodes/group-node';
-import type { BehaviorHandlerFn, BehaviorOptions } from './types';
-import { FormFields } from '../types';
+export interface RegisteredBehavior {
+    /** Handler функция behavior */
+    handler: BehaviorHandlerFn<FormFields>;
+    /** Debounce в миллисекундах */
+    debounce?: number;
+}
 /**
  * Реестр behaviors для формы
  *
  * Каждый экземпляр GroupNode создает собственный реестр (композиция).
  * Устраняет race conditions и изолирует формы друг от друга.
  *
- * Context stack используется для tracking текущего активного реестра:
- * - beginRegistration() помещает this в stack
- * - endRegistration() извлекает из stack
- * - getCurrent() возвращает текущий активный реестр
+ * Наследует AbstractRegistry для унификации:
+ * - Управления global stack
+ * - Template methods begin/end registration
  *
  * @example
  * ```typescript
@@ -30,14 +34,7 @@ import { FormFields } from '../types';
  * }
  * ```
  */
-export declare class BehaviorRegistry {
-    /**
-     * Stack активных контекстов регистрации
-     * Используется для изоляции форм друг от друга
-     */
-    private static contextStack;
-    private registrations;
-    private isRegistering;
+export declare class BehaviorRegistry extends AbstractRegistry<RegisteredBehavior> {
     /**
      * Получить текущий активный реестр из context stack
      *
@@ -55,13 +52,6 @@ export declare class BehaviorRegistry {
      * ```
      */
     static getCurrent(): BehaviorRegistry | null;
-    /**
-     * Начать регистрацию behaviors
-     * Вызывается перед применением схемы
-     *
-     * Помещает this в context stack для изоляции форм
-     */
-    beginRegistration(): void;
     /**
      * Зарегистрировать behavior handler
      * Вызывается функциями из schema-behaviors.ts
@@ -80,8 +70,6 @@ export declare class BehaviorRegistry {
      * Завершить регистрацию и применить behaviors к форме
      * Создает effect подписки для всех зарегистрированных behaviors
      *
-     * Извлекает this из context stack
-     *
      * @param form - GroupNode формы
      * @returns Количество зарегистрированных behaviors и функция cleanup
      */

package/dist/core/behavior/behaviors/compute-from.d.ts

@@ -1,12 +1,5 @@
-/**
- * Вычисляемые поля
- *
- * @group Behaviors
- * @category Behavior Rules
- * @module behaviors/computeFrom
- */
-import type { FieldPathNode } from '../../types';
-import type { ComputeFromOptions } from '../types';
+import { FieldPathNode } from '../../types';
+import { ComputeFromOptions } from '../types';
 /**
  * Автоматически вычисляет значение поля на основе других полей
  *
@@ -16,26 +9,62 @@ import type { ComputeFromOptions } from '../types';
  * @param sources - Массив полей-зависимостей
  * @param target - Поле для записи результата
  * @param computeFn - Функция вычисления (принимает объект с именами полей)
- * @param options - Опции
+ * @param options - Опции (`debounce`, `condition`, `trigger`)
  *
- * @example
+ * @example Многополевой расчёт — total = price × quantity
  * ```typescript
- * const schema: BehaviorSchemaFn<MyForm> = (path) => {
- *   // Автоматический расчет минимального взноса
- *   computeFrom(
- *     [path.propertyValue],
- *     path.initialPayment,
- *     (values) => values.propertyValue ? values.propertyValue * 0.2 : null,
- *     { debounce: 300 }
- *   );
+ * import { computeFrom, type BehaviorSchemaFn } from '@reformer/core/behaviors';
  *
- *   // Общая стоимость = цена * количество
+ * interface OrderForm {
+ *   price: number;
+ *   quantity: number;
+ *   total: number;
+ * }
+ *
+ * export const orderBehavior: BehaviorSchemaFn<OrderForm> = (path) => {
  *   computeFrom(
  *     [path.price, path.quantity],
  *     path.total,
- *     (values) => values.price * values.quantity
+ *     (values) =>
+ *       (typeof values.price === 'number' ? values.price : 0) *
+ *       (typeof values.quantity === 'number' ? values.quantity : 0),
+ *   );
+ * };
+ * ```
+ *
+ * @example Edge case — async-like дорогие вычисления с `debounce` и условием
+ * ```typescript
+ * import { computeFrom, type BehaviorSchemaFn } from '@reformer/core/behaviors';
+ *
+ * interface MortgageForm {
+ *   loanType: 'mortgage' | 'consumer';
+ *   loanAmount: number;
+ *   loanTerm: number;
+ *   interestRate: number;
+ *   monthlyPayment: number;
+ * }
+ *
+ * function annuity(values: MortgageForm): number {
+ *   const { loanAmount, loanTerm, interestRate } = values;
+ *   if (!loanAmount || !loanTerm || !interestRate) return 0;
+ *   const r = interestRate / 100 / 12;
+ *   const n = loanTerm;
+ *   return Math.round((loanAmount * r * Math.pow(1 + r, n)) / (Math.pow(1 + r, n) - 1));
+ * }
+ *
+ * export const mortgageBehavior: BehaviorSchemaFn<MortgageForm> = (path) => {
+ *   computeFrom(
+ *     [path.loanAmount, path.loanTerm, path.interestRate],
+ *     path.monthlyPayment,
+ *     annuity,
+ *     {
+ *       debounce: 300,                                  // не пересчитываем на каждый keystroke
+ *       condition: (form) => form.loanType === 'mortgage', // считаем только для ипотеки
+ *     },
  *   );
  * };
  * ```
+ *
+ * @see [docs/llms/20-compute-vs-watch.md](../../../../docs/llms/20-compute-vs-watch.md)
  */
 export declare function computeFrom<TForm, TTarget>(sources: FieldPathNode<TForm, any>[], target: FieldPathNode<TForm, TTarget>, computeFn: (values: TForm) => TTarget, options?: ComputeFromOptions<TForm>): void;

package/dist/core/behavior/behaviors/copy-from.d.ts

@@ -1,12 +1,5 @@
-/**
- * Копирование значений между полями
- *
- * @group Behaviors
- * @category Behavior Rules
- * @module behaviors/copyFrom
- */
-import type { FieldPathNode } from '../../types';
-import type { CopyFromOptions } from '../types';
+import { FieldPathNode } from '../../types';
+import { CopyFromOptions } from '../types';
 /**
  * Копирует значения из одного поля/группы в другое при выполнении условия
  *
@@ -15,17 +8,49 @@ import type { CopyFromOptions } from '../types';
  *
  * @param source - Откуда копировать
  * @param target - Куда копировать
- * @param options - Опции копирования
+ * @param options - Опции копирования (`when`, `fields`, `transform`, `debounce`)
  *
- * @example
+ * @example Скаляр → скаляр с условием
  * ```typescript
- * const schema: BehaviorSchemaFn<MyForm> = (path) => {
- *   // Копировать адрес регистрации в адрес проживания
+ * import { copyFrom, type BehaviorSchemaFn } from '@reformer/core/behaviors';
+ *
+ * interface ContactForm {
+ *   sameEmail: boolean;
+ *   email: string;
+ *   emailAdditional: string;
+ * }
+ *
+ * export const contactBehavior: BehaviorSchemaFn<ContactForm> = (path) => {
+ *   copyFrom(path.email, path.emailAdditional, {
+ *     when: (form) => form.sameEmail === true,
+ *   });
+ * };
+ * ```
+ *
+ * @example Копирование группы с подмножеством полей и `transform`
+ * ```typescript
+ * import { copyFrom, type BehaviorSchemaFn } from '@reformer/core/behaviors';
+ *
+ * interface Address { country: string; region: string; city: string; street: string }
+ * interface ProfileForm {
+ *   sameAsRegistration: boolean;
+ *   registrationAddress: Address;
+ *   residenceAddress: Address;
+ * }
+ *
+ * export const profileBehavior: BehaviorSchemaFn<ProfileForm> = (path) => {
  *   copyFrom(path.registrationAddress, path.residenceAddress, {
  *     when: (form) => form.sameAsRegistration === true,
- *     fields: 'all'
+ *     fields: ['country', 'region', 'city'], // street НЕ копируем
+ *     transform: (addr) => ({
+ *       ...addr,
+ *       country: addr.country.toUpperCase(), // нормализация при копировании
+ *     }),
+ *     debounce: 200,
  *   });
  * };
  * ```
+ *
+ * @see [docs/llms/23-copy-from.md](../../../../docs/llms/23-copy-from.md)
  */
 export declare function copyFrom<TForm, TSource, TTarget>(source: FieldPathNode<TForm, TSource>, target: FieldPathNode<TForm, TTarget>, options?: CopyFromOptions<TSource, TForm>): void;

package/dist/core/behavior/behaviors/enable-when.d.ts

@@ -1,12 +1,5 @@
-/**
- * Условное включение/отключение полей
- *
- * @group Behaviors
- * @category Behavior Rules
- * @module behaviors/enableWhen
- */
-import type { FieldPathNode } from '../../types';
-import type { EnableWhenOptions } from '../types';
+import { FieldPathNode } from '../../types';
+import { EnableWhenOptions } from '../types';
 /**
  * Условное включение поля на основе значений других полей
  *
@@ -15,17 +8,68 @@ import type { EnableWhenOptions } from '../types';
  *
  * @param field - Поле для включения/выключения
  * @param condition - Функция условия (true = enable, false = disable)
- * @param options - Опции
+ * @param options - Опции (`resetOnDisable`, `debounce`)
  *
- * @example
+ * @example Базовый сценарий с `resetOnDisable: true`
  * ```typescript
- * const schema: BehaviorSchemaFn<MyForm> = (path) => {
- *   // Включить поле только для ипотеки
+ * import { enableWhen, type BehaviorSchemaFn } from '@reformer/core/behaviors';
+ *
+ * interface LoanForm {
+ *   loanType: 'mortgage' | 'consumer' | 'car';
+ *   propertyValue: number;
+ *   initialPayment: number;
+ * }
+ *
+ * export const loanBehavior: BehaviorSchemaFn<LoanForm> = (path) => {
+ *   // Поля ипотеки активны только для loanType === 'mortgage'.
+ *   // resetOnDisable: true гарантирует чистые initial values при переключении.
  *   enableWhen(path.propertyValue, (form) => form.loanType === 'mortgage', {
- *     resetOnDisable: true
+ *     resetOnDisable: true,
+ *   });
+ *   enableWhen(path.initialPayment, (form) => form.loanType === 'mortgage', {
+ *     resetOnDisable: true,
  *   });
  * };
  * ```
+ *
+ * @example Множественные independent условия + cycle prevention
+ * ```typescript
+ * import { enableWhen, type BehaviorSchemaFn } from '@reformer/core/behaviors';
+ *
+ * interface ProfileForm {
+ *   sameAsRegistration: boolean;
+ *   employmentStatus: 'employed' | 'selfEmployed' | 'unemployed';
+ *   residenceAddress: { city: string; street: string };
+ *   companyName: string;
+ *   companyInn: string;
+ *   businessType: string;
+ * }
+ *
+ * export const profileBehavior: BehaviorSchemaFn<ProfileForm> = (path) => {
+ *   // Адрес проживания: enabled, когда НЕ совпадает с регистрационным
+ *   enableWhen(path.residenceAddress, (form) => form.sameAsRegistration === false, {
+ *     resetOnDisable: true,
+ *   });
+ *
+ *   // Поля работодателя: только для employed
+ *   enableWhen(path.companyName, (form) => form.employmentStatus === 'employed', {
+ *     resetOnDisable: true,
+ *   });
+ *   enableWhen(path.companyInn, (form) => form.employmentStatus === 'employed', {
+ *     resetOnDisable: true,
+ *   });
+ *
+ *   // ИП-поля: только для selfEmployed
+ *   enableWhen(path.businessType, (form) => form.employmentStatus === 'selfEmployed', {
+ *     resetOnDisable: true,
+ *   });
+ *
+ *   // ВАЖНО: condition не должен читать значение САМОГО поля — иначе цикл.
+ *   // condition зависит ТОЛЬКО от независимых триггеров (loanType, employmentStatus, ...).
+ * };
+ * ```
+ *
+ * @see [docs/llms/22-cycle-detection.md](../../../../docs/llms/22-cycle-detection.md)
  */
 export declare function enableWhen<TForm>(field: FieldPathNode<TForm, any>, condition: (form: TForm) => boolean, options?: EnableWhenOptions): void;
 /**
@@ -36,13 +80,38 @@ export declare function enableWhen<TForm>(field: FieldPathNode<TForm, any>, cond
  *
  * @param field - Поле для выключения
  * @param condition - Функция условия (true = disable, false = enable)
- * @param options - Опции
+ * @param options - Опции (`resetOnDisable`, `debounce`)
  *
- * @example
+ * @example Базовый сценарий — readonly после подтверждения
  * ```typescript
- * const schema: BehaviorSchemaFn<MyForm> = (path) => {
- *   // Выключить поле для потребительского кредита
- *   disableWhen(path.propertyValue, (form) => form.loanType === 'consumer');
+ * import { disableWhen, type BehaviorSchemaFn } from '@reformer/core/behaviors';
+ *
+ * interface ConfirmForm {
+ *   isConfirmed: boolean;
+ *   editableField: string;
+ * }
+ *
+ * export const confirmBehavior: BehaviorSchemaFn<ConfirmForm> = (path) => {
+ *   // Поле блокируется после установки чекбокса подтверждения
+ *   disableWhen(path.editableField, (form) => form.isConfirmed === true);
+ *   // resetOnDisable НЕ ставим — сохраняем введённый текст
+ * };
+ * ```
+ *
+ * @example С `resetOnDisable` для очистки заблокированного поля
+ * ```typescript
+ * import { disableWhen, type BehaviorSchemaFn } from '@reformer/core/behaviors';
+ *
+ * interface PromoForm {
+ *   loanType: 'mortgage' | 'consumer';
+ *   promoCode: string;
+ * }
+ *
+ * export const promoBehavior: BehaviorSchemaFn<PromoForm> = (path) => {
+ *   // Промокод недоступен для потребительских кредитов и сбрасывается
+ *   disableWhen(path.promoCode, (form) => form.loanType === 'consumer', {
+ *     resetOnDisable: true,
+ *   });
  * };
  * ```
  */

package/dist/core/behavior/behaviors/reset-when.d.ts

@@ -1,11 +1,4 @@
-/**
- * Условный сброс полей
- *
- * @group Behaviors
- * @category Behavior Rules
- * @module behaviors/resetWhen
- */
-import type { FieldPathNode, FormFields, FormValue } from '../../types';
+import { FieldPathNode, FormFields, FormValue } from '../../types';
 /**
  * Опции для resetWhen
  *
@@ -26,25 +19,45 @@ export interface ResetWhenOptions {
  *
  * @param field - Поле для сброса
  * @param condition - Функция условия (true = reset)
- * @param options - Опции
+ * @param options - Опции (`resetValue`, `onlyIfDirty`, `debounce`)
  *
- * @example
+ * @example Сброс зависимого поля при смене типа платежа
  * ```typescript
- * const schema: BehaviorSchemaFn<MyForm> = (path) => {
- *   // Сбросить поле при изменении типа кредита
- *   resetWhen(path.propertyValue, (form) => form.loanType !== 'mortgage');
+ * import { resetWhen, type BehaviorSchemaFn } from '@reformer/core/behaviors';
+ *
+ * interface CheckoutForm {
+ *   paymentType: 'card' | 'cash';
+ *   cardNumber: string;
+ * }
  *
- *   // Сбросить с кастомным значением
- *   resetWhen(path.initialPayment, (form) => !form.propertyValue, {
- *     resetValue: 0
+ * export const checkoutBehavior: BehaviorSchemaFn<CheckoutForm> = (path) => {
+ *   // Когда выбрано НЕ card — обнуляем номер карты в пустую строку
+ *   resetWhen(path.cardNumber, (form) => form.paymentType !== 'card', {
+ *     resetValue: '',
  *   });
+ * };
+ * ```
+ *
+ * @example `onlyIfDirty` — не трогаем нетронутые initial значения
+ * ```typescript
+ * import { resetWhen, type BehaviorSchemaFn } from '@reformer/core/behaviors';
+ *
+ * interface CarForm {
+ *   loanType: 'mortgage' | 'car' | 'consumer';
+ *   carPrice: number;
+ * }
  *
- *   // Сбросить только если поле было изменено пользователем
+ * export const carBehavior: BehaviorSchemaFn<CarForm> = (path) => {
+ *   // Если пользователь не вводил carPrice — оставляем default из схемы.
+ *   // Сбрасываем только если поле dirty (была пользовательская правка).
  *   resetWhen(path.carPrice, (form) => form.loanType !== 'car', {
- *     onlyIfDirty: true
+ *     resetValue: 0,
+ *     onlyIfDirty: true,
  *   });
  * };
  * ```
+ *
+ * @see [docs/llms/25-reset-when.md](../../../../docs/llms/25-reset-when.md)
  */
 export declare function resetWhen<TForm extends FormFields>(field: FieldPathNode<TForm, FormValue>, condition: (form: TForm) => boolean, options?: ResetWhenOptions & {
     debounce?: number;

package/dist/core/behavior/behaviors/revalidate-when.d.ts

@@ -1,12 +1,5 @@
-/**
- * Перевалидация полей при изменениях
- *
- * @group Behaviors
- * @category Behavior Rules
- * @module behaviors/revalidateWhen
- */
-import type { FieldPathNode, FormValue } from '../../types';
-import type { RevalidateWhenOptions } from '../types';
+import { FieldPathNode, FormValue } from '../../types';
+import { RevalidateWhenOptions } from '../types';
 /**
  * Перевалидирует поле при изменении других полей
  *
@@ -14,17 +7,47 @@ import type { RevalidateWhenOptions } from '../types';
  * @category Behavior Rules
  *
  * @param target - Поле для перевалидации
- * @param triggers - Поля-триггеры
- * @param options - Опции
+ * @param triggers - Поля-триггеры (НЕ должно содержать `target`)
+ * @param options - Опции (`debounce`)
+ *
+ * @example Парная перевалидация — confirmPassword при смене password
+ * ```typescript
+ * import { revalidateWhen, type BehaviorSchemaFn } from '@reformer/core/behaviors';
+ * import { equalTo } from '@reformer/core/validators';
+ * import type { FieldPath } from '@reformer/core';
+ *
+ * interface RegistrationForm { password: string; confirmPassword: string }
  *
- * @example
+ * export const validation = (path: FieldPath<RegistrationForm>) => {
+ *   equalTo(path.confirmPassword, path.password, { message: 'Пароли не совпадают' });
+ * };
+ *
+ * export const behavior: BehaviorSchemaFn<RegistrationForm> = (path) => {
+ *   // Если пользователь сначала ввёл confirm, потом меняет password —
+ *   // без revalidateWhen ошибка confirmPassword останется устаревшей.
+ *   revalidateWhen(path.confirmPassword, [path.password]);
+ * };
+ * ```
+ *
+ * @example Несколько триггеров + `debounce` для async-валидаторов
  * ```typescript
- * const schema: BehaviorSchemaFn<MyForm> = (path) => {
- *   // Перевалидировать initialPayment при изменении propertyValue
- *   revalidateWhen(path.initialPayment, [path.propertyValue], {
- *     debounce: 300
- *   });
+ * import { revalidateWhen, type BehaviorSchemaFn } from '@reformer/core/behaviors';
+ *
+ * interface MortgageForm {
+ *   propertyValue: number;
+ *   loanAmount: number;
+ *   initialPayment: number; // правило: initialPayment >= propertyValue * 0.2 - loanAmount
+ * }
+ *
+ * export const mortgageBehavior: BehaviorSchemaFn<MortgageForm> = (path) => {
+ *   revalidateWhen(
+ *     path.initialPayment,
+ *     [path.propertyValue, path.loanAmount],
+ *     { debounce: 300 }, // не дёргаем сервер на каждый keystroke
+ *   );
  * };
  * ```
+ *
+ * @see [docs/llms/27-revalidate-when.md](../../../../docs/llms/27-revalidate-when.md)
  */
 export declare function revalidateWhen<TForm>(target: FieldPathNode<TForm, FormValue>, triggers: FieldPathNode<TForm, FormValue>[], options?: RevalidateWhenOptions): void;

package/dist/core/behavior/behaviors/sync-fields.d.ts

@@ -1,12 +1,5 @@
-/**
- * Двусторонняя синхронизация полей
- *
- * @group Behaviors
- * @category Behavior Rules
- * @module behaviors/syncFields
- */
-import type { FieldPathNode, FormFields, FormValue } from '../../types';
-import type { SyncFieldsOptions } from '../types';
+import { FieldPathNode, FormFields, FormValue } from '../../types';
+import { SyncFieldsOptions } from '../types';
 /**
  * Двусторонняя синхронизация двух полей
  *
@@ -15,14 +8,41 @@ import type { SyncFieldsOptions } from '../types';
  *
  * @param field1 - Первое поле
  * @param field2 - Второе поле
- * @param options - Опции
+ * @param options - Опции (`transform` асимметричен — применяется только field1 → field2; `debounce`)
+ *
+ * @example Базовый mirror двух текстовых полей
+ * ```typescript
+ * import { syncFields, type BehaviorSchemaFn } from '@reformer/core/behaviors';
  *
- * @example
+ * interface MirrorForm {
+ *   syncField1: string;
+ *   syncField2: string;
+ * }
+ *
+ * export const mirrorBehavior: BehaviorSchemaFn<MirrorForm> = (path) => {
+ *   syncFields(path.syncField1, path.syncField2);
+ * };
+ * ```
+ *
+ * @example С `transform` (асимметричный) и `debounce` для защиты от частых перезаписей
  * ```typescript
- * const schema: BehaviorSchemaFn<MyForm> = (path) => {
- *   // Синхронизировать два поля
- *   syncFields(path.email, path.emailCopy);
+ * import { syncFields, type BehaviorSchemaFn } from '@reformer/core/behaviors';
+ *
+ * interface CodeForm {
+ *   internalCode: string;  // канонический формат
+ *   displayCode: string;   // показываем пользователю
+ * }
+ *
+ * export const codeBehavior: BehaviorSchemaFn<CodeForm> = (path) => {
+ *   // internalCode → displayCode: применяется toUpperCase
+ *   // displayCode → internalCode: пишется как есть
+ *   syncFields(path.internalCode, path.displayCode, {
+ *     transform: (value) => (typeof value === 'string' ? value.toUpperCase() : value),
+ *     debounce: 150, // сглаживает дёргание каретки
+ *   });
  * };
  * ```
+ *
+ * @see [docs/llms/24-sync-fields.md](../../../../docs/llms/24-sync-fields.md)
  */
 export declare function syncFields<TForm extends FormFields, T extends FormValue>(field1: FieldPathNode<TForm, T>, field2: FieldPathNode<TForm, T>, options?: SyncFieldsOptions<T>): void;