@reformer/core 1.0.0-beta.3

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

@@ -0,0 +1,308 @@
+/**
+ * ArrayNode - узел формы для работы с массивами
+ *
+ * Управляет массивом форм с поддержкой:
+ * - Динамического добавления/удаления элементов
+ * - Валидации всех элементов
+ * - Реактивного состояния через signals
+ *
+ * @group Nodes
+ */
+import type { ReadonlySignal } from '@preact/signals-core';
+import { FormNode, type SetValueOptions } from './form-node';
+import type { FieldStatus, ValidationError, FormFields } from '../types';
+import type { FormSchema } from '../types/deep-schema';
+import type { GroupNodeWithControls } from '../types/group-node-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 FormFields> extends FormNode<T[]> {
+    private items;
+    private itemSchema;
+    private initialItems;
+    /**
+     * Менеджер подписок для централизованного cleanup
+     * Использует SubscriptionManager вместо массива для управления подписками
+     */
+    private disposers;
+    private validationSchemaFn?;
+    private behaviorSchemaFn?;
+    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 - Индекс элемента для удаления
+     */
+    removeAt(index: number): void;
+    /**
+     * Вставить элемент в массив
+     * @param index - Индекс для вставки
+     * @param initialValue - Начальные значения для нового элемента
+     */
+    insert(index: number, initialValue?: Partial<T>): void;
+    /**
+     * Удалить все элементы массива
+     */
+    clear(): void;
+    /**
+     * Получить элемент по индексу
+     * @param index - Индекс элемента
+     * @returns Типизированный GroupNode или undefined если индекс вне границ
+     */
+    at(index: number): GroupNodeWithControls<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>;
+    setErrors(_errors: ValidationError[]): void;
+    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
+     */
+    forEach(callback: (item: GroupNodeWithControls<T>, index: number) => void): void;
+    /**
+     * Маппинг элементов массива
+     * @param callback - Функция преобразования с типизированным GroupNode
+     * @returns Новый массив результатов
+     */
+    map<R>(callback: (item: GroupNodeWithControls<T>, index: number) => R): R[];
+    /**
+     * Создать новый элемент массива на основе схемы
+     * @param initialValue - Начальные значения
+     */
+    private createItem;
+    /**
+     * Проверить, является ли схема групповой (объект полей)
+     * @param schema - Схема для проверки
+     */
+    private isGroupSchema;
+    /**
+     * Применить validation schema ко всем элементам массива
+     *
+     * Validation schema будет применена к:
+     * - Всем существующим элементам
+     * - Всем новым элементам, добавляемым через push/insert
+     *
+     * @param schemaFn - Функция валидации для элемента массива
+     *
+     * @example
+     * ```typescript
+     * import { propertyValidation } from './validation/property-validation';
+     *
+     * form.properties.applyValidationSchema(propertyValidation);
+     * ```
+     */
+    applyValidationSchema(schemaFn: unknown): void;
+    /**
+     * Применить behavior schema ко всем элементам ArrayNode
+     *
+     * Автоматически применяется к новым элементам при push/insert.
+     *
+     * @param schemaFn - Behavior schema функция
+     *
+     * @example
+     * ```typescript
+     * import { addressBehavior } from './behaviors/address-behavior';
+     *
+     * form.addresses.applyBehaviorSchema(addressBehavior);
+     * ```
+     */
+    applyBehaviorSchema(schemaFn: unknown): void;
+    /**
+     * Подписка на изменения конкретного поля во всех элементах массива
+     * Срабатывает при изменении значения поля в любом элементе
+     *
+     * @param fieldKey - Ключ поля для отслеживания
+     * @param callback - Функция, вызываемая при изменении, получает массив всех значений и индекс измененного элемента
+     * @returns Функция отписки для cleanup
+     *
+     * @example
+     * ```typescript
+     * // Автоматический пересчет общей стоимости при изменении цен
+     * const dispose = form.existingLoans.watchItems(
+     *   'remainingAmount',
+     *   (amounts) => {
+     *     const totalDebt = amounts.reduce((sum, amount) => sum + (amount || 0), 0);
+     *     form.totalDebt.setValue(totalDebt);
+     *   }
+     * );
+     *
+     * // При изменении любого remainingAmount → пересчитается totalDebt
+     * form.existingLoans.at(0)?.remainingAmount.setValue(500000);
+     *
+     * // Cleanup
+     * useEffect(() => dispose, []);
+     * ```
+     */
+    watchItems<K extends keyof T>(fieldKey: K, callback: (values: Array<T[K] | undefined>) => void | Promise<void>): () => void;
+    /**
+     * Подписка на изменение длины массива
+     * Срабатывает при добавлении/удалении элементов
+     *
+     * @param callback - Функция, вызываемая при изменении длины, получает новую длину
+     * @returns Функция отписки для cleanup
+     *
+     * @example
+     * ```typescript
+     * // Обновление счетчика элементов в UI
+     * const dispose = form.properties.watchLength((length) => {
+     *   console.log(`Количество объектов недвижимости: ${length}`);
+     *   form.propertyCount.setValue(length);
+     * });
+     *
+     * form.properties.push({ title: 'Квартира', value: 5000000 });
+     * // Выведет: "Количество объектов недвижимости: 1"
+     *
+     * // Cleanup
+     * useEffect(() => dispose, []);
+     * ```
+     */
+    watchLength(callback: (length: number) => void | Promise<void>): () => void;
+    /**
+     * Очистить все ресурсы узла
+     * Рекурсивно очищает все 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;
+}