@reformer/core 11.0.0-beta.8 → 11.0.0-beta.9

package/dist/form/nodes/array-node.d.ts

@@ -1,276 +0,0 @@
-import { ReadonlySignal } from '@preact/signals-core';
-import { FormNode, SetValueOptions } from './form-node';
-import { FieldStatus, ValidationError } from '../types/index';
-import { FormSchema } from '../types/deep-schema';
-import { FormProxy } from '../types/form-proxy';
-/**
- * ArrayNode - массив форм с реактивным состоянием
- *
- * @group Nodes
- *
- * @example
- * ```typescript
- * const array = new ArrayNode({
- *   title: { value: '', component: Input },
- *   price: { value: 0, component: Input },
- * });
- *
- * array.push({ title: 'Item 1', price: 100 });
- * array.at(0)?.title.setValue('Updated');
- * console.log(array.length.value); // 1
- * ```
- */
-export declare class ArrayNode<T extends object> extends FormNode<T[]> {
-    private items;
-    private itemSchema;
-    private initialItems;
-    /**
-     * Менеджер подписок для централизованного cleanup
-     * Использует SubscriptionManager вместо массива для управления подписками
-     */
-    private disposers;
-    /** Array-level validation errors (e.g., "минимум 1 элемент") */
-    private readonly _arrayErrors;
-    readonly value: ReadonlySignal<T[]>;
-    readonly valid: ReadonlySignal<boolean>;
-    readonly invalid: ReadonlySignal<boolean>;
-    readonly touched: ReadonlySignal<boolean>;
-    readonly dirty: ReadonlySignal<boolean>;
-    readonly pending: ReadonlySignal<boolean>;
-    readonly errors: ReadonlySignal<ValidationError[]>;
-    readonly status: ReadonlySignal<FieldStatus>;
-    readonly length: ReadonlySignal<number>;
-    constructor(schema: FormSchema<T>, initialItems?: Partial<T>[]);
-    /**
-     * Добавить элемент в конец массива
-     * @param initialValue - Начальные значения для нового элемента
-     */
-    push(initialValue?: Partial<T>): void;
-    /**
-     * Удалить элемент по индексу
-     * @param index - Индекс элемента для удаления
-     *
-     * @remarks
-     * Вызывает dispose() на удаляемом элементе для очистки подписок
-     */
-    removeAt(index: number): void;
-    /**
-     * Вставить элемент в массив
-     * @param index - Индекс для вставки
-     * @param initialValue - Начальные значения для нового элемента
-     */
-    insert(index: number, initialValue?: Partial<T>): void;
-    /**
-     * Переместить элемент массива с позиции `from` на позицию `to`
-     *
-     * @param from - Индекс перемещаемого элемента
-     * @param to - Целевой индекс
-     *
-     * @remarks
-     * Реордер не уничтожает элемент (dispose НЕ вызывается) — тот же инстанс под-формы
-     * переезжает на новую позицию, состояние/валидация сохраняются. Длина не меняется.
-     *
-     * @example
-     * ```typescript
-     * // Поднять элемент #2 на одну позицию вверх
-     * form.items.move(2, 1);
-     * ```
-     */
-    move(from: number, to: number): void;
-    /**
-     * Поменять местами два элемента массива
-     *
-     * @param a - Индекс первого элемента
-     * @param b - Индекс второго элемента
-     *
-     * @remarks
-     * Как и {@link move}, не уничтожает элементы — меняет только их порядок.
-     *
-     * @example
-     * ```typescript
-     * form.items.swap(0, 2);
-     * ```
-     */
-    swap(a: number, b: number): void;
-    /**
-     * Удалить все элементы массива
-     *
-     * @remarks
-     * Вызывает dispose() на всех элементах для очистки подписок
-     */
-    clear(): void;
-    /**
-     * Получить элемент по индексу
-     * @param index - Индекс элемента
-     * @returns Типизированный GroupNode proxy или undefined если индекс вне границ
-     */
-    at(index: number): FormProxy<T> | undefined;
-    getValue(): T[];
-    setValue(values: T[], options?: SetValueOptions): void;
-    patchValue(values: (T | undefined)[]): void;
-    /**
-     * Сбросить массив к указанным значениям (или очистить)
-     *
-     * @param values - опциональный массив значений для сброса
-     *
-     * @remarks
-     * Очищает текущий массив и заполняет новыми элементами
-     *
-     * @example
-     * ```typescript
-     * // Очистить массив
-     * arrayNode.reset();
-     *
-     * // Сбросить к новым значениям
-     * arrayNode.reset([{ name: 'Item 1' }, { name: 'Item 2' }]);
-     * ```
-     */
-    reset(values?: T[]): void;
-    /**
-     * Сбросить массив к исходным значениям (initialItems)
-     *
-     * @remarks
-     * Восстанавливает массив в состояние, которое было при создании ArrayNode.
-     * Более явный способ сброса к начальным значениям по сравнению с reset()
-     *
-     * Полезно когда:
-     * - Пользователь нажал "Cancel" - вернуть массив к исходным элементам
-     * - Массив был изменен через reset(newValues), но нужно вернуться к началу
-     * - Явное намерение показать "отмена всех изменений"
-     *
-     * @example
-     * ```typescript
-     * const arrayNode = new ArrayNode(
-     *   { name: { value: '', component: Input } },
-     *   [{ name: 'Initial 1' }, { name: 'Initial 2' }]
-     * );
-     *
-     * arrayNode.push({ name: 'New Item' });
-     * arrayNode.reset([{ name: 'Temp' }]);
-     * console.log(arrayNode.length.value); // 1
-     *
-     * arrayNode.resetToInitial();
-     * console.log(arrayNode.length.value); // 2
-     * console.log(arrayNode.at(0)?.name.value.value); // 'Initial 1'
-     * ```
-     */
-    resetToInitial(): void;
-    validate(): Promise<boolean>;
-    /**
-     * Установить array-level validation errors
-     *
-     * @param errors - Массив ошибок валидации уровня массива
-     *
-     * @example
-     * ```typescript
-     * arrayNode.setErrors([{
-     *   code: 'minItems',
-     *   message: 'Минимум 1 элемент обязателен',
-     * }]);
-     * ```
-     */
-    setErrors(errors: ValidationError[]): void;
-    /**
-     * Очистить все errors (array-level + item-level)
-     *
-     * @example
-     * ```typescript
-     * arrayNode.clearErrors();
-     * console.log(arrayNode.errors.value); // []
-     * ```
-     */
-    clearErrors(): void;
-    /**
-     * Hook: вызывается после markAsTouched()
-     *
-     * Для ArrayNode: рекурсивно помечаем все элементы массива как touched
-     */
-    protected onMarkAsTouched(): void;
-    /**
-     * Hook: вызывается после markAsUntouched()
-     *
-     * Для ArrayNode: рекурсивно помечаем все элементы массива как untouched
-     */
-    protected onMarkAsUntouched(): void;
-    /**
-     * Hook: вызывается после markAsDirty()
-     *
-     * Для ArrayNode: рекурсивно помечаем все элементы массива как dirty
-     */
-    protected onMarkAsDirty(): void;
-    /**
-     * Hook: вызывается после markAsPristine()
-     *
-     * Для ArrayNode: рекурсивно помечаем все элементы массива как pristine
-     */
-    protected onMarkAsPristine(): void;
-    /**
-     * Итерировать по элементам массива
-     * @param callback - Функция, вызываемая для каждого элемента с типизированным GroupNode proxy
-     */
-    forEach(callback: (item: FormProxy<T>, index: number) => void): void;
-    /**
-     * Маппинг элементов массива
-     * @param callback - Функция преобразования с типизированным GroupNode proxy
-     * @returns Новый массив результатов
-     */
-    map<R>(callback: (item: FormProxy<T>, index: number) => R): R[];
-    /**
-     * Создать новый элемент массива на основе схемы
-     * @param initialValue - Начальные значения
-     */
-    private createItem;
-    /**
-     * Проверить, является ли схема групповой (объект полей)
-     * @param schema - Схема для проверки
-     */
-    private isGroupSchema;
-    /**
-     * Очистить все ресурсы узла
-     * Рекурсивно очищает все subscriptions и элементы массива
-     *
-     * @example
-     * ```typescript
-     * useEffect(() => {
-     *   return () => {
-     *     arrayNode.dispose();
-     *   };
-     * }, []);
-     * ```
-     */
-    dispose(): void;
-    /**
-     * Hook: вызывается после disable()
-     *
-     * Для ArrayNode: рекурсивно отключаем все элементы массива
-     *
-     * @example
-     * ```typescript
-     * // Отключить весь массив полей
-     * form.items.disable();
-     *
-     * // Все элементы становятся disabled
-     * form.items.forEach(item => {
-     *   console.log(item.status.value); // 'disabled'
-     * });
-     * ```
-     */
-    protected onDisable(): void;
-    /**
-     * Hook: вызывается после enable()
-     *
-     * Для ArrayNode: рекурсивно включаем все элементы массива
-     *
-     * @example
-     * ```typescript
-     * // Включить весь массив полей
-     * form.items.enable();
-     *
-     * // Все элементы становятся enabled
-     * form.items.forEach(item => {
-     *   console.log(item.status.value); // 'valid' или 'invalid'
-     * });
-     * ```
-     */
-    protected onEnable(): void;
-}

package/dist/form/nodes/field-node.d.ts

@@ -1,297 +0,0 @@
-import { ReadonlySignal } from '@preact/signals-core';
-import { FormNode, SetValueOptions } from './form-node';
-import { FieldConfig, FieldStatus, ValidationError } from '../types/index';
-/**
- * FieldNode - узел для отдельного поля формы
- *
- * @group Nodes
- *
- * @example
- * Пример node-level: конфиг УЗЛА, а не layout-схема M1 (в ней поля `validators` нет).
- * ```typescript
- * const field = new FieldNode({
- *   value: '',
- *   component: Input,
- *   validators: [required, email],
- * });
- *
- * field.setValue('test@mail.com');
- * await field.validate();
- * console.log(field.valid.value); // true
- * ```
- */
-export declare class FieldNode<T> extends FormNode<T> {
-    private _value;
-    private _errors;
-    private _componentProps;
-    /**
-     * State machine для управления статусом поля
-     * Централизует логику переходов между valid/invalid/pending/disabled
-     */
-    private readonly statusMachine;
-    readonly value: ReadonlySignal<T>;
-    readonly valid: ReadonlySignal<boolean>;
-    readonly invalid: ReadonlySignal<boolean>;
-    readonly pending: ReadonlySignal<boolean>;
-    readonly status: ReadonlySignal<FieldStatus>;
-    readonly disabled: ReadonlySignal<boolean>;
-    readonly errors: ReadonlySignal<ValidationError[]>;
-    readonly componentProps: ReadonlySignal<Record<string, unknown>>;
-    /**
-     * Вычисляемое свойство: нужно ли показывать ошибку
-     * Ошибка показывается если поле невалидно И (touched ИЛИ dirty)
-     */
-    readonly shouldShowError: ReadonlySignal<boolean>;
-    private validators;
-    private asyncValidators;
-    private updateOn;
-    private initialValue;
-    private currentAbortController?;
-    private debounceMs;
-    private validateDebounceTimer?;
-    /**
-     * Pending debounced validation state
-     * Contains resolve function and AbortController for cancellation
-     */
-    private pendingValidation?;
-    /**
-     * Менеджер подписок для централизованного cleanup
-     * Использует SubscriptionManager вместо массива для управления подписками
-     */
-    private disposers;
-    readonly component: FieldConfig<T>['component'];
-    constructor(config: FieldConfig<T>);
-    getValue(): T;
-    setValue(value: T, options?: SetValueOptions): void;
-    patchValue(value: Partial<T>): void;
-    /**
-     * Сбросить поле к указанному значению (или к initialValue)
-     *
-     * @param value - опциональное значение для сброса. Если не указано, используется initialValue
-     *
-     * @remarks
-     * Этот метод:
-     * - Устанавливает значение в value или initialValue
-     * - Очищает ошибки валидации
-     * - Сбрасывает touched/dirty флаги
-     * - Устанавливает статус в 'valid'
-     *
-     * Если вам нужно сбросить к исходному значению, используйте resetToInitial()
-     *
-     * @example
-     * ```typescript
-     * // Сброс к initialValue
-     * field.reset();
-     *
-     * // Сброс к новому значению
-     * field.reset('new value');
-     * ```
-     */
-    reset(value?: T): void;
-    /**
-     * Сбросить поле к исходному значению (initialValue)
-     *
-     * @remarks
-     * Алиас для reset() без параметров, но более явный:
-     * - resetToInitial() - явно показывает намерение вернуться к начальному значению
-     * - reset() - может принимать новое значение
-     *
-     * Полезно когда:
-     * - Пользователь нажал "Cancel" - вернуть форму в исходное состояние
-     * - Форма была изменена через reset(newValue), но нужно вернуться к самому началу
-     * - Явное намерение показать "отмену всех изменений"
-     *
-     * @example
-     * ```typescript
-     * const field = new FieldNode({ value: 'initial', component: Input });
-     *
-     * field.setValue('changed');
-     * field.reset('temp value');
-     * console.log(field.value.value); // 'temp value'
-     *
-     * field.resetToInitial();
-     * console.log(field.value.value); // 'initial'
-     * ```
-     */
-    resetToInitial(): void;
-    /**
-     * Cancel any pending validation (debounced or running)
-     * @private
-     * @remarks
-     * Centralizes all cancellation logic:
-     * - Aborts pending debounced validation and resolves its promise
-     * - Clears debounce timer
-     * - Aborts currently running async validation
-     */
-    private cancelPendingValidation;
-    /**
-     * Запустить валидацию поля
-     * @param options - опции валидации
-     * @returns `Promise<boolean>` - true если поле валидно
-     *
-     * @remarks
-     * Метод защищен от race conditions через AbortController.
-     * При быстром вводе только последняя валидация применяет результаты.
-     *
-     * @example
-     * ```typescript
-     * // Обычная валидация
-     * await field.validate();
-     *
-     * // С debounce
-     * await field.validate({ debounce: 300 });
-     * ```
-     */
-    validate(options?: {
-        debounce?: number;
-    }): Promise<boolean>;
-    /**
-     * Немедленная валидация без debounce
-     * @private
-     * @param providedController - AbortController from debounced validate()
-     * @remarks
-     * Защищена от race conditions через AbortController:
-     * - Отменяет предыдущую валидацию при запуске новой (if no controller provided)
-     * - Передаёт AbortSignal в async валидаторы для отмены операций (например, fetch)
-     * - Проверяет signal.aborted в ключевых точках
-     */
-    private validateImmediate;
-    setErrors(errors: ValidationError[]): void;
-    clearErrors(): void;
-    /**
-     * Hook: вызывается после markAsTouched()
-     *
-     * Для FieldNode: если updateOn === 'blur', запускаем валидацию
-     */
-    protected onMarkAsTouched(): void;
-    /**
-     * Hook: вызывается после disable()
-     *
-     * Для FieldNode: синхронизируем statusMachine и очищаем ошибки
-     */
-    protected onDisable(): void;
-    /**
-     * Hook: вызывается после enable()
-     *
-     * Для FieldNode: синхронизируем statusMachine и запускаем валидацию
-     */
-    protected onEnable(): void;
-    /**
-     * Обновляет свойства компонента (например, опции для Select)
-     *
-     * @example
-     * ```typescript
-     * // Обновление опций для Select после загрузки справочников
-     * form.registrationAddress.city.updateComponentProps({
-     *   options: cities
-     * });
-     * ```
-     */
-    updateComponentProps(props: Partial<Record<string, unknown>>): void;
-    /**
-     * Динамически изменяет триггер валидации (updateOn)
-     * Полезно для адаптивной валидации - например, переключиться на instant feedback после первого submit
-     *
-     * @param updateOn - новый триггер валидации: 'change' | 'blur' | 'submit'
-     *
-     * @example
-     * Пример node-level: плоская схема с инлайн-значениями (back-compat путь до M1). В layout-схеме
-     * `createFormFromModel({ model, schema })` поля `validators` нет — правила живут в `defineValidationSchema`.
-     * ```typescript
-     * // Сценарий 1: Instant feedback после submit
-     * const form = createLegacyForm({
-     *   email: {
-     *     value: '',
-     *     component: Input,
-     *     updateOn: 'submit', // Изначально валидация только при submit
-     *     validators: [required, email],
-     *   },
-     * });
-     *
-     * await form.submit(async (values) => {
-     *   // После submit переключаем на instant feedback
-     *   form.email.setUpdateOn('change');
-     *   await api.save(values);
-     * });
-     *
-     * // Теперь валидация происходит при каждом изменении
-     *
-     * // Сценарий 2: Прогрессивное улучшение
-     * form.email.setUpdateOn('blur');  // Сначала только при blur
-     * // ... пользователь начинает вводить ...
-     * form.email.setUpdateOn('change'); // Переключаем на change для real-time feedback
-     * ```
-     */
-    setUpdateOn(updateOn: 'change' | 'blur' | 'submit'): void;
-    getUpdateOn(): 'change' | 'blur' | 'submit';
-    /**
-     * Подписка на изменения значения поля
-     * Автоматически отслеживает изменения через @preact/signals effect
-     *
-     * @param callback - Функция, вызываемая при изменении значения.
-     *   Для async операций передается AbortSignal во втором параметре.
-     * @returns Функция отписки для cleanup
-     *
-     * @example
-     * ```typescript
-     * // Синхронный callback
-     * const unsubscribe = form.email.watch((value) => {
-     *   console.log('Email changed:', value);
-     * });
-     *
-     * // Асинхронный callback с поддержкой отмены
-     * const unsubscribe = form.email.watch(async (value, signal) => {
-     *   const result = await fetch('/api/validate', { signal });
-     *   // ...
-     * });
-     *
-     * // Cleanup
-     * useEffect(() => unsubscribe, []);
-     * ```
-     */
-    watch(callback: (value: T, signal: AbortSignal) => void | Promise<void>): () => void;
-    /**
-     * Вычисляемое значение из других полей
-     * Автоматически обновляет текущее поле при изменении источников
-     *
-     * @param sources - Массив ReadonlySignal для отслеживания
-     * @param computeFn - Функция вычисления нового значения
-     * @returns Функция отписки для cleanup
-     *
-     * @example
-     * ```typescript
-     * // Автоматический расчет первоначального взноса (20% от стоимости)
-     * const dispose = form.initialPayment.computeFrom(
-     *   [form.propertyValue.value],
-     *   (propertyValue) => {
-     *     return propertyValue ? propertyValue * 0.2 : null;
-     *   }
-     * );
-     *
-     * // Cleanup
-     * useEffect(() => dispose, []);
-     * ```
-     */
-    computeFrom<TSource extends readonly unknown[]>(sources: ReadonlySignal<TSource[number]>[], computeFn: (...values: TSource) => T): () => void;
-    /**
-     * Очистить все ресурсы и таймеры
-     * Должен вызываться при unmount компонента
-     *
-     * @remarks
-     * Освобождает все ресурсы:
-     * - Отписывает все subscriptions через SubscriptionManager
-     * - Отменяет pending/running валидации через cancelPendingValidation()
-     *
-     * Использует try-finally для гарантированного cleanup даже при ошибках.
-     *
-     * @example
-     * ```typescript
-     * useEffect(() => {
-     *   return () => {
-     *     field.dispose();
-     *   };
-     * }, []);
-     * ```
-     */
-    dispose(): void;
-}