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

package/llms.txt

@@ -113,14 +113,15 @@ const { value, errors, disabled } = useFormControl(control.loanType);
 > `Checkbox`-обёртки с `label`-prop'ами — это anti-pattern. См.
 > `find_recipe(package="@reformer/ui-kit", topic="form-field-integration")`.
 
-Архитектура M1: сначала создаётся **модель данных** (`createModel`), затем **форма**
-(`createForm({ model, schema })`), где схема привязывает поля к сигналам модели
-(`model.$.field`). Layout-схема НЕ несёт валидаторов — валидация живёт в отдельной
+Архитектура M1: **модель данных** — источник истины, схема привязывает поля к её сигналам
+(`model.$.field`), а сборка идёт ОДНИМ вызовом `createCoreForm` (для рендера ui-kit;
+в рендерерах — `createReactForm` / `createJsonForm`), который создаёт модель, строит форму,
+запускает поведение и собирает валидацию. Layout-схема НЕ несёт валидаторов — валидация живёт в отдельной
 схеме `defineValidationSchema` из `@reformer/core/validation` и запускается внешним
 раннером `validateModel(model, schema)`.
 
 ```typescript
-import { createModel, createForm, type FormProxy } from '@reformer/core';
+import { createCoreForm, createModel, useFormBundle, type FormProxy } from '@reformer/core';
 import { defineValidationSchema, validate, validateModel } from '@reformer/core/validation';
 import { required, email } from '@reformer/core/validators';
 import { FormField, Input, Button } from '@reformer/ui-kit';
@@ -155,8 +156,14 @@ const contactValidation = defineValidationSchema<ContactForm>(({ model }) => {
   validate(model.$.email, [required({ message: 'Email is required' }), email({ message: 'Invalid email' })]);
 });
 
-// 5. Form — ноды поверх сигналов модели
-const form = createForm<ContactForm>({ model, schema });
+// 5. Сборка ОДНИМ вызовом: модель + ноды поверх её сигналов + валидация.
+//    В React оборачивают в useFormBundle — ленивый useState, фабрика зовётся один раз.
+const contact = createCoreForm<ContactForm>({
+  model,
+  schema: buildSchema,          // билдер (model) => tree
+  validation: contactValidation,
+});
+const form = contact.form;
 
 // 6. Use in React component — thin JSX, FormField does ALL heavy lifting
 function ContactFormComponent() {
@@ -227,7 +234,7 @@ const schema = {
   properties: { array: model.properties, item: propertyItem },
 };
 
-const form = createForm<MyForm>({ model, schema });
+const { form } = createCoreForm<MyForm>({ model, schema: () => schema });
 
 // Операции над массивом — на модели:
 model.properties.push({ type: 'apartment', description: '', estimatedValue: 0 });
@@ -1653,7 +1660,7 @@ src/
 │
 ├── forms/
 │   └── [form-name]/              # Form module — flat, one file per concern
-│       ├── index.tsx             # entry + whole form: createModel→createForm→<FormWizard> with all steps inline; arrays via FormArraySection
+│       ├── index.tsx             # entry + whole form: ONE createCoreForm call → <FormWizard> with all steps inline; arrays via FormArraySection
 │       ├── types.ts              # form type + enums + { value, label } option type + constant dictionaries
 │       ├── model.ts              # createModel + initial values + empty-array-element factories
 │       ├── form.schema.ts        # FormSchema: { value: model.$.x, component, componentProps }
@@ -1698,11 +1705,15 @@ export const creditApplicationBehavior = defineFormBehavior<CreditApplicationFor
 });
 
 // forms/credit-application/index.tsx — entry: assembles the form, renders <FormWizard> with all steps inline
-import { createForm } from '@reformer/core';
-export const createCreditApplicationForm = () => {
-  const model = createCreditApplicationModel();
-  return createForm({ model, schema: creditApplicationSchema(model), behavior: creditApplicationBehavior });
-};
+import { createCoreForm } from '@reformer/core';
+// ONE call: model + form + behavior + validation. In the page: useFormBundle(createCreditApplicationForm).
+export const createCreditApplicationForm = () =>
+  createCoreForm({
+    model: createCreditApplicationModel(),
+    schema: creditApplicationSchema,          // builder (model) => tree
+    behavior: creditApplicationBehavior,
+    validation: creditApplicationValidation,  // { steps, extras } → bundle.validation
+  });
 ```
 
 ### Scaling up: folders (large forms)
@@ -1728,10 +1739,10 @@ forms/
     │
     ├── schema/                   # The form definition
     │   ├── model.ts             # createModel factory + initial values + array-element factories
-    │   ├── schema.ts            # createForm schema tree ({ value: model.$.x, component })
+    │   ├── schema.ts            # schema builder (model) => tree ({ value: model.$.x, component })
     │   ├── validation.ts        # defineValidationSchema + validateModel config ({ validateStep, validateAll })
     │   ├── behavior.ts          # defineFormBehavior(...)
-    │   └── create-form.ts       # Assembly: createForm({ model, schema, behavior })
+    │   └── create-form.ts       # Assembly: createCoreForm({ model, schema, behavior, validation })
     │
     └── components/
         ├── steps/               # One component per wizard step
@@ -2259,9 +2270,38 @@ model.$.email.peek();        // нереактивный снимок
 model.$.address.city.value;  // сигнал вложенного поля (≡ model.address.$.city у под-модели)
 
 // весь объект
-model.get();                 // снимок { email, address: { city }, ... } — для submit
+model.get();                 // НЕреактивный снимок { email, address: { city }, ... } — для submit
+```
+
+> ⚠️ `model.get()` и `model.isDirty()` читают через `peek()` — внутри `effect`/`computed` они НЕ
+> создают зависимостей. `computed(() => model.get())` никогда не пересчитается. Для реактивного
+> чтения всего объекта — узел дерева `$` (ниже).
+
+### Подписка на группу и на модель целиком
+
+Каждый узел дерева `$` — сигнал: лист отдаёт `PathAwareSignal`, а корень, вложенные объекты-группы
+и массивы — `ReadonlySignal` агрегированного значения поддерева. Поэтому подписаться можно на любом
+уровне, а не только на конкретном поле.
+
+```typescript
+model.$.subscribe((all) => autosave(all));      // любое изменение модели; all: T целиком
+model.$.address.subscribe((addr) => ...);       // только поддерево address
+model.$.address.value;                          // реактивный снимок группы
+model.$.address.peek();                         // нереактивный снимок группы
+model.$.items.subscribe((rows) => ...);         // массив: и правка элемента, и push/removeAt/move
+
+// узел — обычный ReadonlySignal, поэтому принимается операциями слоя данных
+watchField(model.$.address, (addr) => geocode(addr));
 ```
 
+Дети узла доступны как раньше — `model.$.address.city` по-прежнему сигнал поля. Подписчик вызывается
+сразу с текущим значением (семантика `Signal.subscribe`), а `model.set(...)`/`model.reset()`
+уведомляют один раз, а не по разу на поле.
+
+> ⚠️ Доступ к полю выигрывает у свойства сигнала: если в форме есть поле с именем `value`, `peek`,
+> `subscribe`, `valueOf`, `toString`, `toJSON` или `brand`, то `model.$.<группа>.<это имя>` вернёт
+> сигнал поля. `subscribe` при этом продолжает работать.
+
 ### В behaviors — читаем model напрямую
 
 `compute`/`onChange`/условия `when` читают значения из value-модели (`model.field`) —
@@ -2411,6 +2451,14 @@ import { watchField } from '@reformer/core';
 const stop = watchField(model.$.country, () => { model.city = ''; });
 ```
 
+Источником может быть не только поле: узлы-контейнеры дерева `$` (корень, группы, массивы) — тоже
+`ReadonlySignal`, поэтому за поддеревом целиком следят без перечисления полей.
+
+```typescript
+watchField(model.$.address, (addr) => geocode(addr));  // любое поле address
+watchField(model.$, (all) => autosave(all));           // любое поле формы
+```
+
 ### Rule of Thumb
 
 | Scenario | Use |
@@ -2419,6 +2467,7 @@ const stop = watchField(model.$.country, () => { model.city = ''; });
 | Производное с явными зависимостями | `computeFrom` |
 | Async-реакция, обновление componentProps | `onChange` (debounce + AbortSignal) |
 | Простая синхронная реакция (примитив) | `watchField` |
+| Реакция на любое изменение группы/формы | `watchField(model.$.<группа>)` или `.subscribe` |
 
 ### Chained computeds
 
@@ -4608,6 +4657,43 @@ export type BehaviorCleanup = () => void;
 
 _Source: src/state/behaviors-value.ts_
 
+### buildValidation
+
+**Kind:** `function`
+
+Собрать {@link FormValidationBundle} из правил. Принимает либо готовую схему (сахар для простых
+форм), либо {@link FormValidation} с шагами и стратегией.
+
+Схема для `validateAll` собирается ОДИН раз на бандл — иначе ломается дедупликация прогонов.
+
+**Signature:**
+```typescript
+export function buildValidation<T>(
+  model: FormModel<T>,
+  validation?: FormValidation<T> | ValidationSchema<T>
+): FormValidationBundle<T> | undefined
+```
+
+**Parameters:**
+- `model` — - Модель, по которой идут прогоны.
+- `validation` — - Правила; `undefined` — валидации у формы нет.
+
+**Returns:** Бандл валидации либо `undefined`, если правила не заданы.
+
+**Examples:**
+
+```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
+```
+
+_Source: src/form/validation-config.ts_
+
 ### computeFrom
 
 **Kind:** `function`
@@ -4727,6 +4813,75 @@ stampRuntime('@reformer/core', CORE_RUNTIME_TOKEN);
 
 _Source: src/runtime-token.ts_
 
+### CoreForm
+
+**Kind:** `interface`
+
+Результат {@link createCoreForm}: модель, форма и (если заданы правила) собранная валидация.
+
+**Signature:**
+```typescript
+export interface CoreForm<T> {
+  model: FormModel<T>;
+  form: FormProxy<T>;
+  validation?: FormValidationBundle<T>;
+}
+```
+
+_Source: src/form/create-core-form.ts_
+
+### createCoreForm
+
+**Kind:** `function`
+
+Собрать модель, форму и валидацию за один проход.
+
+**Signature:**
+```typescript
+export function createCoreForm<T extends object>(config: CreateCoreFormConfig<T>): CoreForm<T>
+```
+
+**Parameters:**
+- `config` — - {@link CreateCoreFormConfig}: (`initial` | `model`) + опц. `schema`, `behavior`,
+`validation`, `seed`, `setup`.
+
+**Returns:** 
+
+**Examples:**
+
+```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} />;
+```
+
+_Source: src/form/create-core-form.ts_
+
+### CreateCoreFormConfig
+
+**Kind:** `interface`
+
+Конфиг {@link createCoreForm}.
+
+**Signature:**
+```typescript
+export interface CreateCoreFormConfig<T> extends CreateFormConfigBase<T, CoreForm<T>> {
+  /**
+   * Билдер схемы формы. Именно функция, а не готовое дерево: листья схемы держат сами сигналы
+   * модели (`value: model.$.email`), поэтому построить дерево до модели нечем.
+   */
+  schema?: (model: FormModel<T>) => FormSchemaNode;
+}
+```
+
+_Source: src/form/create-core-form.ts_
+
 ### createForm
 
 **Kind:** `function`
@@ -4779,6 +4934,40 @@ const ok = await validateModel(model, validation);
 
 _Source: src/form/create-form.ts_
 
+### CreateFormConfigBase
+
+**Kind:** `interface`
+
+Общая часть конфига всех фабрик формы.
+
+**Signature:**
+```typescript
+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;
+}
+```
+
+_Source: src/form/create-core-form.ts_
+
 ### createFormFromModel
 
 **Kind:** `function`
@@ -5393,6 +5582,21 @@ todos.forEach((item, i) => {
 
 _Source: src/form/types/form-proxy.ts_
 
+### FormBundleLike
+
+**Kind:** `interface`
+
+Минимум, который хук ожидает от бандла: опциональный контроллер живой валидации.
+
+**Signature:**
+```typescript
+export interface FormBundleLike {
+  validation?: { controller: FormValidationController };
+}
+```
+
+_Source: src/form/hooks/use-form-bundle.ts_
+
 ### FormControlsProxy
 
 **Kind:** `type`
@@ -5785,6 +5989,70 @@ if (submitter.submitting.value) {
 
 _Source: src/form/form-submitter.ts_
 
+### FormValidation
+
+**Kind:** `interface`
+
+Правила валидации формы — ДАННЫЕ (без привязки к рендеру).
+
+⚠️ `schema` и значения `steps` обязаны быть **стабильными ссылками**: отмена устаревших прогонов
+ключуется по паре `(model, schema)` через `WeakMap`, поэтому инлайн-стрелка ломает дедупликацию —
+валидация начнёт возвращать `false` от уже отменённых прогонов. Держите их
+module-level-константами (`defineValidationSchema`).
+
+**Signature:**
+```typescript
+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';
+}
+```
+
+_Source: src/form/validation-config.ts_
+
+### FormValidationBundle
+
+**Kind:** `interface`
+
+Собранная валидация формы. Структурно совместима с `FormWizardConfig` и `StepValidationConfig`
+из `@reformer/cdk`, поэтому уходит в визард как есть: `config={bundle.validation}` либо
+`patchProps({ form, ...bundle.validation })`.
+
+**Signature:**
+```typescript
+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>;
+}
+```
+
+_Source: src/form/validation-config.ts_
+
 ### FormValue
 
 **Kind:** `type`
@@ -6077,6 +6345,29 @@ if (isGroupNode(node)) {
 
 _Source: src/form/type-guards.ts_
 
+### isModelContainerSignal
+
+**Kind:** `function`
+
+Узел дерева `model.$` — контейнер (группа/массив), а не лист?
+
+Контейнерный узел структурно совместим с `ReadonlySignal` (`peek`/`value`/`subscribe`), поэтому
+duck-typing «есть `peek` ⇒ это лист» на нём даёт ложное срабатывание. Этот guard — надёжный
+способ различить: обходчикам дерева нужно спускаться в контейнер, а не читать его целиком.
+
+**Signature:**
+```typescript
+export function isModelContainerSignal(value: unknown): boolean
+```
+
+**Examples:**
+
+```typescript
+const isLeaf = (v: unknown) => isSignalLike(v) && !isModelContainerSignal(v);
+```
+
+_Source: src/state/form-model.ts_
+
 ### markDerived
 
 **Kind:** `function`
@@ -6125,8 +6416,11 @@ API уровня модели (доступно на корне, под-моде
 **Signature:**
 ```typescript
 export interface ModelApi<T> {
-  /** Escape-hatch к сигналам: `model.$.loanType` → `PathAwareSignal<LoanType>`. */
-  readonly $: ModelSignals<T>;
+  /**
+   * Escape-hatch к сигналам: `model.$.loanType` → `PathAwareSignal<LoanType>`.
+   * Сам узел — {@link ReadonlySignal} модели целиком: `model.$.subscribe(v => …)`.
+   */
+  readonly $: ModelGroupSignals<T>;
   /** Снимок значений (без подписки) — для submit. */
   get(): T;
   /**
@@ -6270,6 +6564,41 @@ rows.length.value;                  // 1 (реактивная длина)
 
 _Source: src/form/nodes/model-array-node.ts_
 
+### ModelArraySignals
+
+**Kind:** `type`
+
+Узел-массив дерева `model.$`: индексируемый доступ к под-сигналам элементов, реактивная `length`
+и {@link ReadonlySignal} значения массива целиком (реагирует и на правку элемента, и на изменение
+состава — push/removeAt/move).
+
+**Signature:**
+```typescript
+export type ModelArraySignals<U, V> = ContainerSignal<V, 'length'> & {
+  readonly length: number;
+  readonly [index: number]: ModelSignalNode<U>;
+};
+```
+
+_Source: src/state/types.ts_
+
+### ModelGroupSignals
+
+**Kind:** `type`
+
+Узел-группа дерева `model.$`: доступ к под-сигналам полей ({@link ModelSignals}) И одновременно
+{@link ReadonlySignal} агрегированного значения группы — `.value`/`.peek()`/`.subscribe()`.
+
+⚠️ Поле формы с именем `value`/`peek`/`subscribe`/`valueOf`/`toString`/`toJSON`/`brand` затеняет
+одноимённое свойство сигнала (редкий краевой случай); `subscribe` при этом продолжает работать.
+
+**Signature:**
+```typescript
+export type ModelGroupSignals<T> = ModelSignals<T> & ContainerSignal<T, keyof T>;
+```
+
+_Source: src/state/types.ts_
+
 ### ModelObject
 
 **Kind:** `type`
@@ -6291,8 +6620,8 @@ _Source: src/state/types.ts_
 
 **Kind:** `type`
 
-Дерево сигналов (escape-hatch `model.$`): листья → {@link PathAwareSignal},
-объекты → вложенное дерево, массивы → индексируемое дерево под-сигналов.
+Карта под-сигналов объекта в дереве `model.$` (без свойств самого узла — их добавляет
+{@link ModelGroupSignals}).
 
 **Signature:**
 ```typescript
@@ -6884,6 +7213,31 @@ function ArrayRenderer({ arrayNode }) {
 
 _Source: src/form/hooks/useArrayLength.ts_
 
+### useFormBundle
+
+**Kind:** `function`
+
+Собрать форму один раз и держать её стабильной; живую стратегию валидации армировать в эффекте
+(не при SSR — там эффекты не выполняются).
+
+**Signature:**
+```typescript
+export function useFormBundle<B extends FormBundleLike>(factory: () => B): B
+```
+
+**Parameters:**
+- `factory` — - Фабрика бандла, обычно `() => createCoreForm({…})`.
+
+**Returns:** Стабильный бандл.
+
+**Examples:**
+
+```tsx
+const credit = useFormBundle(() => createCoreForm<CreditForm>({ model: createCreditModel() }));
+```
+
+_Source: src/form/hooks/use-form-bundle.ts_
+
 ### useFormControl
 
 **Kind:** `function`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reformer/core",
-  "version": "11.0.0-beta.1",
+  "version": "11.0.0-beta.3",
   "description": "Reactive form state management library for React with signals-based architecture",
   "type": "module",
   "main": "./dist/index.js",

package/dist/derived-registry-CluZCQ7U.js

@@ -1,16 +0,0 @@
-const t = /* @__PURE__ */ new WeakMap();
-function n(e) {
-  t.set(e, (t.get(e) ?? 0) + 1);
-}
-function i(e) {
-  const r = t.get(e);
-  r !== void 0 && (r <= 1 ? t.delete(e) : t.set(e, r - 1));
-}
-function o(e) {
-  return t.has(e);
-}
-export {
-  o as i,
-  n as m,
-  i as u
-};