@reformer/core 9.0.0-beta.1 → 9.0.0-beta.2

package/dist/core/types/validation-schema.d.ts

@@ -35,27 +35,37 @@ import { FormModel } from '../model/types';
 export type Validator<TForm, TField> = (value: TField, scope: unknown, root: FormModel<TForm>) => ValidationError | null;
 /**
  * Чистый асинхронный валидатор поля. Та же тройка аргументов `(value, scope, root)`, что у
- * {@link Validator}, но возвращает `Promise`. Регистрируется через
- * `validateAsync(path, validator, { debounce })`.
+ * {@link Validator}, но возвращает `Promise`.
+ *
+ * @deprecated Осиротевший остаток удалённого оператора `validateAsync` (Ф7). Рантаймом не
+ * потребляется — живой async-путь узла поля использует `AsyncValidatorFn` `(value, { signal })`.
+ * Экспортируется только ради обратной совместимости.
  */
 export type AsyncValidator<TForm, TField> = (value: TField, scope: unknown, root: FormModel<TForm>) => Promise<ValidationError | null>;
 /**
- * Функция условия для applyWhen.
+ * Функция-предикат `(value) => boolean`.
+ *
+ * @deprecated Осиротевший остаток удалённого оператора `applyWhen` (Ф7). Рантаймом не
+ * потребляется; экспортируется только ради обратной совместимости.
  */
 export type ConditionFn<T> = (value: T) => boolean;
 /**
- * Опции для функции validate.
+ * Опции валидатора-фабрики (`required()`/`pattern()`/…). Передаются вторым (или последним)
+ * аргументом в фабрику и попадают в возвращаемую {@link ValidationError}.
  */
 export interface ValidateOptions {
-    /** Сообщение об ошибке */
+    /** Готовое сообщение об ошибке. Если не задано, валидаторы кладут `''`, и отображаемый текст
+     * резолвится из `code` (см. резолвер сообщений в `@reformer/cdk`). */
     message?: string;
-    /** Параметры ошибки */
+    /** Параметры ошибки (подстановка в шаблон сообщения / i18n). */
     params?: Record<string, FormValue>;
 }
 /**
- * Опции для функции validateAsync.
+ * @deprecated Осиротевший остаток удалённого оператора `validateAsync` (Ф7): опция `debounce`
+ * подключалась тем оператором, которого больше нет. Рантаймом не потребляется; экспортируется
+ * только ради обратной совместимости.
  */
 export interface ValidateAsyncOptions extends ValidateOptions {
-    /** Задержка перед выполнением валидации (в мс) */
+    /** Задержка перед выполнением валидации (в мс). */
     debounce?: number;
 }

package/dist/core/utils/derived-registry.d.ts

@@ -6,6 +6,9 @@ import { Signal } from '@preact/signals-core';
  * bulk-сеттеры (`model.set`/`model.patch`, `patchValue`/`setValue`) пропускают это поле, чтобы
  * значение из payload не затирало вычисляемое. Прикладной код напрямую обычно не вызывает.
  *
+ * Идемпотентна на уровне флага: повторные вызовы наращивают счётчик ссылок, чтобы каждый оператор,
+ * пишущий в этот сигнал, был сбалансирован своим {@link unmarkDerived} при dispose.
+ *
  * @param signal - Сигнал значения из {@link FormModel}, которым владеет compute
  *
  * @example
@@ -17,9 +20,35 @@ import { Signal } from '@preact/signals-core';
  * ```
  *
  * @see {@link isDerived} - проверка пометки
+ * @see {@link unmarkDerived} - снять пометку при dispose оператора
  * @group Utilities
  */
 export declare function markDerived(signal: Signal<any>): void;
+/**
+ * Снять пометку производного сигнала (обратная операция к {@link markDerived}).
+ *
+ * Вызывается из очистки (`onDispose`) оператора `compute`/`computeFrom`, когда поведение снимается,
+ * но модель/сигнал продолжают жить (динамическая перекоммутация: удалить под-схему → сохранить модель
+ * → bulk-set). Без этого сигнал остаётся помеченным навсегда, и bulk-сеттеры навсегда пропускают
+ * поле, которое больше ничем не вычисляется.
+ *
+ * Учитывает счётчик ссылок: пометка снимается только когда снят последний владелец. Вызов на
+ * непомеченном сигнале — безопасный no-op.
+ *
+ * @param signal - Сигнал значения из {@link FormModel}, ранее помеченный {@link markDerived}
+ *
+ * @example
+ * ```typescript
+ * import { markDerived, unmarkDerived } from '@reformer/core';
+ *
+ * markDerived(model.$.total);
+ * onDispose(() => unmarkDerived(model.$.total)); // при снятии compute снова разрешаем bulk-set
+ * ```
+ *
+ * @see {@link markDerived} - пометить сигнал производным
+ * @group Utilities
+ */
+export declare function unmarkDerived(signal: Signal<any>): void;
 /**
  * Производный ли сигнал (помечен через {@link markDerived}).
  *

package/dist/core/utils/form-submitter.d.ts

@@ -70,7 +70,12 @@ export declare class FormSubmitter<T extends object> {
      *
      * @param onSubmit - Callback для отправки данных
      * @param options - Опции submit
-     * @returns Результат от onSubmit или null если валидация не пройдена
+     * @returns Результат от onSubmit или `null` если валидация не пройдена
+     *
+     * @remarks
+     * Возвращаемый `null` неоднозначен: он сигналит и провал валидации, и легитимный `null`,
+     * который вернул `onSubmit` (или void-обработчик). Чтобы различать эти случаи, используйте
+     * {@link submitWithResult} — он отдаёт явный флаг `success`.
      *
      * @example
      * ```typescript

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

@@ -9,7 +9,7 @@ export { FormErrorHandler, ErrorStrategy } from './error-handler';
 export { createForm, createFormFromModel } from './create-form';
 export type { CreateFormFromModelArgs } from './create-form';
 export { registerSignalNode, getNodeForSignal } from './signal-node-registry';
-export { markDerived, isDerived } from './derived-registry';
+export { markDerived, isDerived, unmarkDerived } from './derived-registry';
 export { uniqueId } from './unique-id';
 export { safeCallback, runOutsideEffect, safeDebouncedCallback } from './safe-effect';
 export { FormSubmitter } from './form-submitter';

package/dist/core/utils/safe-effect.d.ts

@@ -4,14 +4,28 @@
  * Эти утилиты решают проблему "Cycle detected" в @preact/signals-core,
  * которая возникает при модификации сигналов внутри effect.
  *
+ * Отложенная запись ({@link runOutsideEffect}) откладывается на микротаск и при этом:
+ * - маршрутизирует синхронные throws и async-rejection через {@link FormErrorHandler} вместо того,
+ *   чтобы они всплывали неперехваченными в точке микротаска / тонули как unhandledRejection;
+ * - возвращает отменитель (canceller) для liveness — вызывающий может отменить ещё не выполненную
+ *   запись при dispose, чтобы она не сработала против снесённого узла/формы.
+ *
+ * NB: намеренно НЕ оборачиваем записи в `batch()`. Реципрокные guard'ы слоя данных (например
+ * `syncFields` в {@link module:core/model/behaviors}) держат флаг «идёт синхронизация» и сбрасывают его
+ * в `finally` ПОСЛЕ записи, полагаясь на то, что встречный эффект флашится СИНХРОННО во время записи
+ * (вне batch). `batch()` отложил бы встречный флаш за пределы сброса флага и сломал бы эту защиту
+ * (сходимость осталась бы за peek-guard'ом, но появились бы лишние круги). Коалесинг записей в один
+ * batch — законная оптимизация, но она требует, чтобы эти guard'ы стали batch-aware, поэтому делается
+ * не здесь. См. также `aggregateInto`, где коалесинг реализован на уровне самого оператора.
+ *
  * @group Utils
  * @module utils/safe-effect
  */
 /**
  * Создает callback, который выполняется вне контекста effect
  *
- * Использует queueMicrotask для отложенного выполнения,
- * что позволяет модифицировать сигналы без вызова "Cycle detected"
+ * Откладывает вызов через {@link runOutsideEffect} — то есть получает маршрутизацию ошибок и
+ * обработку async-rejection «бесплатно».
  *
  * @param callback - Функция для выполнения
  * @returns Обёрнутая функция, безопасная для вызова внутри effect
@@ -33,27 +47,33 @@
  */
 export declare function safeCallback<TArgs extends unknown[]>(callback: (...args: TArgs) => void | Promise<void>): (...args: TArgs) => void;
 /**
- * Выполняет функцию вне контекста effect
+ * Выполняет функцию вне контекста effect (отложенная запись на микротаск).
  *
- * Более простой вариант для одиночного вызова
+ * Сбои fn (синхронный throw и async-rejection) маршрутизируются через {@link FormErrorHandler}, а не
+ * всплывают неперехваченными. Возвращает отменитель: вызов до срабатывания микротаска отменяет запись
+ * (liveness-охрана — не писать против снесённого узла при dispose в том же тике).
  *
  * @param fn - Функция для выполнения
+ * @returns Отменитель ещё не выполненной записи (no-op, если запись уже выполнена)
  *
  * @example
  * ```typescript
  * effect(() => {
  *   const value = signal.value;
- *   runOutsideEffect(() => {
+ *   const cancel = runOutsideEffect(() => {
  *     otherSignal.value = transform(value);
  *   });
+ *   onDispose(cancel); // отменить ожидающую запись, если узел снесут в этом же тике
  * });
  * ```
  */
-export declare function runOutsideEffect(fn: () => void | Promise<void>): void;
+export declare function runOutsideEffect(fn: () => void | Promise<void>): () => void;
 /**
  * Создает версию callback с поддержкой debounce, безопасную для effect
  *
- * Комбинирует debounce логику с выходом из effect контекста
+ * `withDebounce` уже откладывает вызов (таймер) — этого достаточно для выхода из effect-контекста,
+ * поэтому дополнительного `queueMicrotask` нет (устранён двойной defer). Сбои callback (в т.ч.
+ * async-rejection) маршрутизируются через {@link FormErrorHandler}.
  *
  * @param callback - Функция для выполнения
  * @param withDebounce - Функция debounce обёртки из BehaviorRegistry

package/dist/core/validation/validators/required.d.ts

@@ -4,7 +4,8 @@ import { Validator, ValidateOptions } from '../../types/validation-schema';
  *
  * Возвращает чистую функцию-валидатор `(value, control, root)`. Передаётся в `validate()`.
  *
- * Пустыми считаются: `null`, `undefined`, `''` (пустая строка).
+ * Пустыми считаются: `null`, `undefined`, `''` (пустая строка), `[]` (пустой массив —
+ * обязательный multi-select / FormArray без выбранных элементов).
  * Для boolean полей требуется значение `true`.
  *
  * @param options - Опции валидатора ({@link ValidateOptions}): `message`, `params`

package/dist/hooks/types.d.ts

@@ -191,6 +191,20 @@ export interface FieldControlState<T> {
      * ```
      */
     componentProps: Record<string, unknown>;
+    /**
+     * Флаг изменения поля.
+     * `true` когда значение поля отличается от начального.
+     *
+     * Реактивный аналог `control.dirty` — паритет с {@link ArrayControlState.dirty}.
+     *
+     * @example
+     * ```tsx
+     * const { dirty } = useFormControl(field);
+     *
+     * return dirty ? <span className="badge">Изменено</span> : null;
+     * ```
+     */
+    dirty: boolean;
 }
 /**
  * Состояние массива формы, возвращаемое хуком {@link useFormControl} для {@link ArrayNode}.
@@ -325,4 +339,20 @@ export interface ArrayControlState<T> {
      * ```
      */
     dirty: boolean;
+    /**
+     * Флаг отключения массива.
+     * `true` когда массив отключён (`ArrayNode.disable()`), в том числе через
+     * распространение disable от родительской группы.
+     *
+     * Используйте для отключения UI-действий добавления/удаления, когда массив
+     * структурно неизменяем.
+     *
+     * @example
+     * ```tsx
+     * const { disabled } = useFormControl(itemsArray);
+     *
+     * return <button disabled={disabled} onClick={() => control.push()}>Add</button>;
+     * ```
+     */
+    disabled: boolean;
 }

package/dist/hooks/useSignalSubscription.d.ts

@@ -14,4 +14,11 @@ export interface SignalConfig<K extends string> {
  * Хук для подписки на набор сигналов с кешированием
  * @internal
  */
-export declare function useSignalSubscription<TSignals extends SignalMap, TSnapshot extends ExtractSignalValues<TSignals>>(signals: TSignals, configs: SignalConfig<Extract<keyof TSignals, string>>[], buildSnapshot: (values: ExtractSignalValues<TSignals>) => TSnapshot): TSnapshot;
+export declare function useSignalSubscription<TSignals extends SignalMap, TSnapshot extends ExtractSignalValues<TSignals>>(signals: TSignals, configs: SignalConfig<Extract<keyof TSignals, string>>[], buildSnapshot: (values: ExtractSignalValues<TSignals>) => TSnapshot, 
+/**
+ * Стабильная идентичность подписки (обычно сам узел-контрол). subscribe/getSnapshot
+ * пересоздаются ТОЛЬКО при её смене, а не на каждом рендере — как у useFormControlValue,
+ * который ключует по `[control]`. Это убирает per-render churn (dispose+recreate preact-effect),
+ * сохраняя реактивность при подмене контрола на другой узел.
+ */
+subscriptionKey?: unknown): TSnapshot;