@reformer/core 11.0.0-beta.2 → 11.0.0-beta.3

package/dist/form/create-core-form.d.ts

@@ -0,0 +1,70 @@
+import { FormModel } from '../state/types';
+import { FormSchemaNode } from './types/schema-node';
+import { FormBehavior } from './behaviors';
+import { FormProxy } from './types/index';
+import { FormValidation, FormValidationBundle } from './validation-config';
+import { ValidationSchema } from './validation-schema';
+/**
+ * Общая часть конфига всех фабрик формы.
+ *
+ * @typeParam T - Форма данных модели.
+ * @typeParam B - Бандл конкретной фабрики (его получает {@link CreateFormConfigBase.setup}).
+ */
+export interface CreateFormConfigBase<T, B> {
+    /** Начальные значения — из них создаётся модель. Взаимоисключимо с `model`. */
+    initial?: T;
+    /** Готовая модель (если создана отдельной фабрикой). Приоритетнее `initial`. */
+    model?: FormModel<T>;
+    /** Декларативное поведение модели (compute/copyFrom/enableWhen/onChange). */
+    behavior?: FormBehavior<T>;
+    /** Правила валидации: готовая схема либо {@link FormValidation} со стратегией и шагами. */
+    validation?: FormValidation<T> | ValidationSchema<T>;
+    /**
+     * Правка модели ДО сборки формы. Нужна там, где значение обязано существовать к моменту
+     * построения нод — например, массив, наполняемый из вычислений (реактивные `onChange` на
+     * инициализации не срабатывают).
+     */
+    seed?: (model: FormModel<T>) => void;
+    /**
+     * Донастройка ПОСЛЕ сборки. Единственное место для правок, которые обязаны идти следом за
+     * `createForm`: поле, чьё значение уже массив, ноды не получает (см. `buildModelConfig`),
+     * поэтому такой префилл выполняется здесь.
+     */
+    setup?: (bundle: B) => void;
+}
+/** Результат {@link createCoreForm}: модель, форма и (если заданы правила) собранная валидация. */
+export interface CoreForm<T> {
+    model: FormModel<T>;
+    form: FormProxy<T>;
+    validation?: FormValidationBundle<T>;
+}
+/** Конфиг {@link createCoreForm}. */
+export interface CreateCoreFormConfig<T> extends CreateFormConfigBase<T, CoreForm<T>> {
+    /**
+     * Билдер схемы формы. Именно функция, а не готовое дерево: листья схемы держат сами сигналы
+     * модели (`value: model.$.email`), поэтому построить дерево до модели нечем.
+     */
+    schema?: (model: FormModel<T>) => FormSchemaNode;
+}
+/**
+ * Собрать модель, форму и валидацию за один проход.
+ *
+ * @typeParam T - Форма данных модели.
+ * @param config - {@link CreateCoreFormConfig}: (`initial` | `model`) + опц. `schema`, `behavior`,
+ *   `validation`, `seed`, `setup`.
+ * @returns {@link CoreForm}` <T>` — `{ model, form, validation? }`.
+ *
+ * @example
+ * ```tsx
+ * const credit = useFormBundle(() =>
+ *   createCoreForm<CreditForm>({
+ *     model: createCreditModel(),
+ *     schema: buildCreditSchema,
+ *     behavior: creditBehavior,
+ *     validation: { steps: { loan: loanRules, confirm: null }, extras: crossRules },
+ *   })
+ * );
+ * return <FormWizard form={credit.form} config={credit.validation} steps={STEPS} />;
+ * ```
+ */
+export declare function createCoreForm<T extends object>(config: CreateCoreFormConfig<T>): CoreForm<T>;

package/dist/form/hooks/use-form-bundle.d.ts

@@ -0,0 +1,26 @@
+import { FormValidationController } from '../validation-strategy';
+/** Минимум, который хук ожидает от бандла: опциональный контроллер живой валидации. */
+export interface FormBundleLike {
+    validation?: {
+        controller: FormValidationController;
+    };
+}
+/**
+ * Собрать форму один раз и держать её стабильной; живую стратегию валидации армировать в эффекте
+ * (не при SSR — там эффекты не выполняются).
+ *
+ * @typeParam B - Тип бандла конкретной фабрики.
+ * @param factory - Фабрика бандла, обычно `() => createCoreForm({…})`.
+ * @returns Стабильный бандл.
+ *
+ * @example
+ * ```tsx
+ * const credit = useFormBundle(() => createCoreForm<CreditForm>({ model: createCreditModel() }));
+ * ```
+ *
+ * @remarks
+ * Передавайте именно фабрику: `useState` трактует функцию как ленивый инициализатор, а некоторые
+ * части бандла сами являются функциями (`RenderSchemaProxy`), поэтому `useFormBundle(bundle.render)`
+ * вызвал бы её вместо сохранения.
+ */
+export declare function useFormBundle<B extends FormBundleLike>(factory: () => B): B;

package/dist/form/index.d.ts

@@ -19,6 +19,12 @@ export { ModelArrayNode } from './nodes/model-array-node';
 export type { ModelArrayControl } from './nodes/model-array-node';
 export { createForm, createFormFromModel } from './create-form';
 export type { CreateFormFromModelArgs } from './create-form';
+export { createCoreForm } from './create-core-form';
+export type { CoreForm, CreateCoreFormConfig, CreateFormConfigBase } from './create-core-form';
+export { buildValidation } from './validation-config';
+export type { FormValidation, FormValidationBundle } from './validation-config';
+export { useFormBundle } from './hooks/use-form-bundle';
+export type { FormBundleLike } from './hooks/use-form-bundle';
 export { enableWhen, disableWhen } from './behaviors-node';
 export { FormErrorHandler, ErrorStrategy } from './error-handler';
 export { registerSignalNode, getNodeForSignal } from './signal-node-registry';

package/dist/form/validation-config.d.ts

@@ -0,0 +1,73 @@
+import { ReadonlySignal } from '@preact/signals-core';
+import { FormModel } from '../state/types';
+import { ValidationSchema } from './validation-schema';
+import { FormValidationController, ValidationStrategyKind } from './validation-strategy';
+/**
+ * Правила валидации формы — ДАННЫЕ (без привязки к рендеру).
+ *
+ * ⚠️ `schema` и значения `steps` обязаны быть **стабильными ссылками**: отмена устаревших прогонов
+ * ключуется по паре `(model, schema)` через `WeakMap`, поэтому инлайн-стрелка ломает дедупликацию —
+ * валидация начнёт возвращать `false` от уже отменённых прогонов. Держите их
+ * module-level-константами (`defineValidationSchema`).
+ */
+export interface FormValidation<T> {
+    /** Полный набор правил — для submit и `validateAll`. Без него собирается из `steps` + `extras`. */
+    schema?: ValidationSchema<T>;
+    /**
+     * Пошаговая валидация визарда: ключ = `selector` шага. `null` означает «шаг без правил» ЯВНО —
+     * чтобы опечатка в ключе не выглядела как пустой шаг.
+     */
+    steps?: Record<string, ValidationSchema<T> | null>;
+    /** Cross-field правила, которые проверяются только целиком (в `validateAll`), но не по шагам. */
+    extras?: ValidationSchema<T>;
+    /** Когда запускать живую валидацию. По умолчанию `'submit'` (реактивно молчит). */
+    strategy?: ValidationStrategyKind;
+    debounce?: number;
+    /** Режим live-фазы для `afterFirstSubmit`. По умолчанию `'change'`. */
+    liveAfterSubmit?: 'change' | 'blur';
+}
+/**
+ * Собранная валидация формы. Структурно совместима с `FormWizardConfig` и `StepValidationConfig`
+ * из `@reformer/cdk`, поэтому уходит в визард как есть: `config={bundle.validation}` либо
+ * `patchProps({ form, ...bundle.validation })`.
+ */
+export interface FormValidationBundle<T> {
+    /** Полная схема (стабильная ссылка) — та, по которой идёт `validateAll`. */
+    readonly schema: ValidationSchema<T>;
+    /** Селекторы шагов в порядке объявления. Пусто, если `steps` не заданы. */
+    readonly stepSelectors: readonly string[];
+    /** Полный прогон с раскрытием ошибок. Синоним {@link FormValidationBundle.validateAll}. */
+    validate(): Promise<boolean>;
+    validateAll(): Promise<boolean>;
+    /** Прогон правил одного шага: по номеру (1-based, как у визарда) или по селектору. */
+    validateStep(step: number | string): Promise<boolean>;
+    /** Контроллер живой валидации ШАГА; `null` — у шага нет правил либо стратегия `submit`. */
+    createStepController(step: number | string): FormValidationController | null;
+    /** Контроллер живой валидации ФОРМЫ. Армится хуком (`useFormBundle`), не фабрикой. */
+    readonly controller: FormValidationController;
+    /** Идёт ли прогон — реактивный сигнал (для тонкой подписки в UI). */
+    readonly validating: ReadonlySignal<boolean>;
+}
+/**
+ * Собрать {@link FormValidationBundle} из правил. Принимает либо готовую схему (сахар для простых
+ * форм), либо {@link FormValidation} с шагами и стратегией.
+ *
+ * Схема для `validateAll` собирается ОДИН раз на бандл — иначе ломается дедупликация прогонов.
+ *
+ * @typeParam T - Форма данных модели.
+ * @param model - Модель, по которой идут прогоны.
+ * @param validation - Правила; `undefined` — валидации у формы нет.
+ * @returns Бандл валидации либо `undefined`, если правила не заданы.
+ *
+ * @example
+ * ```ts
+ * const v = buildValidation(model, {
+ *   steps: { loan: loanRules, applicant: applicantRules, confirm: null },
+ *   extras: crossFieldRules,
+ *   strategy: 'blur',
+ * });
+ * await v!.validateStep(1);   // правила шага `loan`
+ * await v!.validateAll();     // все шаги + extras
+ * ```
+ */
+export declare function buildValidation<T>(model: FormModel<T>, validation?: FormValidation<T> | ValidationSchema<T>): FormValidationBundle<T> | undefined;

package/dist/form/validation-strategy.d.ts

@@ -23,9 +23,15 @@ export interface FormValidationController {
      * `afterFirstSubmit` в live-фазу. Возвращает `false`, если есть блокирующие ошибки.
      */
     validate(): Promise<boolean>;
-    /** Армировать реактивные подписки стратегии. Идемпотентно. Возвращает `dispose`. НЕ звать при SSR. */
+    /**
+     * Армировать реактивные подписки стратегии. Идемпотентно. Возвращает `dispose`. НЕ звать при SSR.
+     *
+     * После {@link FormValidationController.dispose} контроллер армируется ЗАНОВО: React монтирует
+     * компоненты повторно (StrictMode в разработке, remount по роуту), и «одноразовый» контроллер
+     * после такого цикла молча оставался бы без живой валидации.
+     */
     start(): () => void;
-    /** Снять подписки/таймеры. Идемпотентно. */
+    /** Снять подписки/таймеры. Идемпотентно; после него `start()` снова армирует стратегию. */
     dispose(): void;
     /** Идёт ли прогон (submit или live) — снапшот. */
     readonly isValidating: boolean;