@reformer/core 10.0.0-beta.3 → 10.0.0-beta.4

package/docs/llms/07-complete-import.md

@@ -0,0 +1,99 @@
+## Import Patterns
+
+```typescript
+// Модель, форма, хуки, типы, примитивы behaviors — из @reformer/core
+import {
+  // фабрики
+  createModel,
+  createForm,
+  // хуки
+  useFormControl,
+  useFormControlValue,
+  useArrayLength,
+  // примитивы behaviors (принимают сигналы, возвращают cleanup)
+  computeFrom,
+  copyFrom,
+  watchField,
+  enableWhen,
+  disableWhen,
+  transformValue,
+  resetWhen,
+  syncFields,
+  revalidateWhen,
+} from '@reformer/core';
+
+// Типы
+import type {
+  FormModel,        // реактивная модель данных
+  FormProxy,        // тип формы для props компонентов
+  FieldNode,        // узел одного поля
+  GroupNode,        // узел группы
+  ArrayNode,        // узел массива
+  ModelArray,       // реактивный массив модели (push/removeAt/at/map/length)
+  ModelSignals,     // дерево сигналов ($)
+  PathAwareSignal,  // сигнал, знающий свой путь
+  ValidationError,
+  FieldConfig,      // { value, component, componentProps?, ... } — layout, БЕЗ валидаторов
+  FormSchema,
+  FieldControlState,
+} from '@reformer/core';
+
+// Схема валидации: операторы + раннер — из /validation
+import {
+  defineValidationSchema,
+  validate,
+  validateAsync,
+  validateWhen,
+  cross,
+  each,
+  apply,
+  validateModel, // раннер: validateModel(model, schema) => Promise<boolean>
+} from '@reformer/core/validation';
+import type {
+  Rule,             // (value) => ValidationError | null
+  AsyncRule,        // (value, { signal }) => Promise<ValidationError | null>
+  ValidationSchema,
+} from '@reformer/core/validation';
+
+// Валидаторы — чистые фабрики из /validators (кладутся в validate(sig, [...]))
+import { required, min, max, email, minLength, pattern } from '@reformer/core/validators';
+
+// Декларативный DSL behaviors — из /behaviors
+import {
+  defineFormBehavior,
+  compute,
+  computeFrom,
+  copyFrom,
+  onChange,
+  enableWhen,
+  disableWhen,
+  transformValue,
+  resetWhen,
+  syncFields,
+  revalidateWhen,
+  apply,
+  applyEach,
+  aggregateInto,
+  exclusiveFlag,
+} from '@reformer/core/behaviors';
+```
+
+### Form-shape тип должен быть `type`, а не `interface`
+
+Прокси `createForm<T>` и типы `ArrayNode<U>` / `GroupNode<U>` требуют, чтобы form-shape
+структурно совпадал с `Record<string, FormValue>`. У `interface` нет неявной index signature,
+поэтому объявляй form-shape (и типы элементов массива, и вложенные группы) через `type`-alias:
+
+```typescript
+export type AddressForm = {
+  street: string;
+  city: string;
+};
+
+export type CoBorrower = {
+  fullName: string;
+  phone: string;
+};
+```
+
+См. `30-type-safety-recipes.md`.

package/docs/llms/08-form-types.md

@@ -0,0 +1,47 @@
+## 7. FORM TYPE DEFINITION
+
+Form-shape объявляй через `type`-alias (не `interface` — см. `30-type-safety-recipes.md`).
+Тип описывает форму ДАННЫХ (то, что кладётся в `createModel`), без узлов/сигналов.
+
+```typescript
+// CORRECT form type definition
+type MyForm = {
+  // Required fields
+  name: string;
+  email: string;
+
+  // Optional fields — конвенция для форм: null («пользователь очистил»)
+  phone: string | null;
+  age: number | null;
+
+  // Enum/union types
+  status: 'active' | 'inactive';
+
+  // Nested objects
+  address: {
+    street: string;
+    city: string;
+  };
+
+  // Arrays of objects — model-owned (см. 10-arrays.md)
+  items: Array<{
+    id: string;
+    name: string;
+  }>;
+};
+
+// Модель создаётся из initial-значений этого типа
+const model = createModel<MyForm>({
+  name: '',
+  email: '',
+  phone: null,
+  age: null,
+  status: 'active',
+  address: { street: '', city: '' },
+  items: [],
+});
+```
+
+`number | null` / `string | null` работают со встроенными валидаторами напрямую —
+`min`/`max`/`minLength`/`minDate`/`minAge` пропускают пустые значения внутри, guard `if (v != null)`
+не нужен.

package/docs/llms/09-formschema.md

@@ -0,0 +1,143 @@
+## 8. SCHEMA FORMAT (CRITICALLY IMPORTANT)
+
+Под M1 схема **привязывает поле к сигналу модели** (`value: model.$.field`) и держит
+UI-конфиг (`component`/`componentProps`). Значения принадлежат модели. Валидаторов в
+layout-схеме НЕТ — правила живут в отдельной схеме `defineValidationSchema` из
+`@reformer/core/validation` и запускаются раннером `validateModel(model, schema)`.
+
+### Field node
+
+```typescript
+{
+  value: model.$.fieldName,   // сигнал модели (PathAwareSignal) — обязателен
+  component: Input,           // React-компонент
+  componentProps?: object,    // пропсы (label, placeholder, options, type, ...)
+  disabled?: boolean,
+  updateOn?: 'change' | 'blur' | 'submit',
+  debounce?: number,
+}
+```
+
+> `disabled` — **top-level поле узла** (начальное состояние); дальше управляется методами
+> `form.field.disable()`/`enable()` и оператором `enableWhen`. `componentProps.disabled` — это
+> UI-проп и на состояние узла **не влияет** (частая причина «computed-поле остаётся редактируемым»).
+
+### Primitive Fields
+
+```typescript
+import { createModel, createForm } from '@reformer/core';
+import { defineValidationSchema, validate } from '@reformer/core/validation';
+import { required } from '@reformer/core/validators';
+import { Input, Select, Checkbox } from '@reformer/ui-kit';
+
+const model = createModel<MyForm>({ name: '', age: null, agree: false, status: 'active' });
+
+// Валидация — отдельным слоем (запуск: await validateModel(model, myValidation))
+const myValidation = defineValidationSchema<MyForm>(({ model }) => {
+  validate(model.$.name, [required()]);
+});
+
+const schema = {
+  name: {
+    value: model.$.name,
+    component: Input,
+    componentProps: { label: 'Name', placeholder: 'Enter name' },
+  },
+  age: {
+    value: model.$.age,
+    component: Input,
+    componentProps: { type: 'number', label: 'Age' },
+  },
+  agree: {
+    value: model.$.agree,
+    component: Checkbox,
+    componentProps: { label: 'I agree to terms' },
+  },
+  status: {
+    value: model.$.status,
+    component: Select,
+    componentProps: {
+      label: 'Status',
+      options: [
+        { value: 'active', label: 'Active' },
+        { value: 'inactive', label: 'Inactive' },
+      ],
+    },
+  },
+};
+
+const form = createForm<MyForm>({ model, schema });
+```
+
+### Nested Objects
+
+Вложенная группа модели — это сама по себе под-модель `FormModel<Sub>` (доступна как `model.<group>`,
+с `.$`/API). Удобно вынести в builder, принимающий `FormModel<Sub>` — симметрично builder'у элемента
+массива. Сигналы под-модели идентичны корневым: `model.address.$.city === model.$.address.city`.
+
+```typescript
+import type { FormModel } from '@reformer/core';
+
+const addressNodes = (m: FormModel<Address>) => ({
+  street: { value: m.$.street, component: Input, componentProps: { label: 'Street' } },
+  city:   { value: m.$.city,   component: Input, componentProps: { label: 'City' } },
+  zip:    { value: m.$.zip,    component: Input, componentProps: { label: 'ZIP' } },
+});
+
+const schema = {
+  address: addressNodes(model.address),
+};
+```
+
+### Arrays — `{ array, item }` node
+
+Массив объектов объявляется узлом `{ array: model.<path>, item: (itemModel) => subSchema }`.
+`item` строит под-схему из под-модели элемента (`FormModel<Item>`):
+
+```typescript
+import type { FormModel } from '@reformer/core';
+
+const itemSchema = (item: FormModel<Item>) => ({
+  id:   { value: item.$.id,   component: Input, componentProps: { label: 'ID' } },
+  name: { value: item.$.name, component: Input, componentProps: { label: 'Name' } },
+});
+
+const schema = {
+  items: { array: model.items, item: itemSchema },
+};
+```
+
+### createForm API
+
+```typescript
+// M1: данные из модели + схема (+ опциональный декларативный behavior)
+const form = createForm<MyForm>({
+  model,                 // FormModel<MyForm> — обязателен
+  schema,                // дерево узлов, привязанных к сигналам
+  behavior: myBehavior,  // опционально: defineFormBehavior(...) из @reformer/core/behaviors
+});
+
+// Доступ к нодам через Proxy
+form.name.setValue('John');
+form.address.city.value.value;  // текущее значение (через сигнал)
+model.items.push({ id: '1', name: 'Item' }); // операции над массивом — на модели
+```
+
+> **Тип `schema` в M1 — `unknown`, не `FormSchema<T>`.** Это осознанно: интерпретатор обходит
+> произвольную структуру и собирает листья `{ value: signal, component?, ... }`, поэтому обёртки
+> (`{ children: [...] }`, wizard/steps) компилируются. Строгий `FormSchema<T>` (keyed-map по полям
+> `T`) применяется только на legacy-пути `createForm(schema)` без модели.
+
+### createForm Returns a Proxy
+
+```typescript
+const form = createForm<MyForm>({ model, schema });
+
+form.email;          // FieldNode<string> — TypeScript знает тип
+form.address.city;   // FieldNode<string> — вложенный доступ
+form.items.at(0);    // FormProxy<ItemType> — элемент массива
+
+// IMPORTANT: Proxy не проходит instanceof! Используй type guards:
+import { isFieldNode, isGroupNode, isArrayNode } from '@reformer/core';
+if (isFieldNode(node)) { /* ... */ }
+```

package/docs/llms/10-arrays.md

@@ -0,0 +1,161 @@
+## 9. ARRAY SCHEMA FORMAT
+
+Массивы объектов — **model-owned**: данные принадлежат модели (`model.arrayField` — это
+`ModelArray<Item>` с реактивными `push`/`removeAt`/`length`). В схеме массив объявляется узлом
+`{ array: model.<path>, item: (itemModel) => subSchema }`, где `item` строит под-схему одного
+элемента из его под-модели (`FormModel<Item>`).
+
+```typescript
+import { createModel, createForm, type FormModel } from '@reformer/core';
+import { Input } from '@reformer/ui-kit';
+
+type Item = { id: string; name: string; price: number };
+type MyForm = { items: Item[] };
+
+const model = createModel<MyForm>({ items: [] });
+
+// под-схема одного элемента (item.$.field — сигнал под-модели)
+const itemSchema = (item: FormModel<Item>) => ({
+  id:    { value: item.$.id,    component: Input },
+  name:  { value: item.$.name,  component: Input },
+  price: { value: item.$.price, component: Input, componentProps: { type: 'number' } },
+});
+
+const schema = {
+  items: { array: model.items, item: itemSchema },
+};
+
+const form = createForm<MyForm>({ model, schema });
+```
+
+> **Type constraint:** тип элемента `Item` объявляй через `type`-alias (не `interface`) — иначе
+> он не совместим с `Record<string, FormValue>` и `ArrayNode<Item>` его отвергнет.
+> См. `30-type-safety-recipes.md`.
+
+### Один массив — три слоя (три разных движка)
+
+Одна и та же коллекция описывается **тремя разными формами** — по одной на движок. Их легко
+перепутать, но каждая корректна только в своём контексте:
+
+1. **Layout-схема `createForm`** — единственная форма, которую ест `createForm`:
+   `{ array: model.<path>, item: (itemModel) => subSchema }`. Массив связывается через
+   **value-proxy** `model.properties` (он несёт `__path`), а **не** через сигнальный
+   `model.$.properties`.
+
+   ```typescript
+   // узел схемы для createForm({ model, schema })
+   properties: { array: model.properties, item: propertyItem },
+   ```
+
+2. **Validation-схема (`@reformer/core/validation`)** — per-item правила пишутся оператором
+   `each(arr, (im) => {...})` внутри `defineValidationSchema`; `im` — под-модель элемента
+   (`im.$.field` — его сигналы). Запуск — внешним `validateModel(model, schema)`.
+
+   ```typescript
+   // внутри defineValidationSchema<MyForm>(({ model }) => { ... })
+   each(model.properties, (im) => {
+     validate(im.$.description, [required()]);
+     validate(im.$.estimatedValue, [required(), min(1)]);
+   });
+   ```
+
+3. **CDK / render** — работают с уже **материализованной** нодой `form.<array>` (`ModelArrayNode`),
+   а не со схемой: `<FormArray.Root control={form.properties}>` (CDK) или `FormArraySection` из
+   `@reformer/ui-kit` (`control={form.properties}`, `itemComponent`).
+
+> **Не путай форму по движку.** `createForm` принимает **только** `{ array, item }`;
+> per-item валидация — это `each(model.<array>, (im) => ...)` в validation-схеме; `FormArray.Root
+> control={form.x}` (или `FormArraySection`) — рендер. `each` в layout-схеме `createForm`
+> не подхватится, а `{ array, item }` в validation-схеме не обходится.
+
+### Array operations — на модели
+
+Мутации массива делаются через `ModelArray` (`model.items`), а не через ноду формы:
+
+```typescript
+model.items.push({ id: '1', name: '', price: 0 });   // добавить в конец (плоские значения!)
+model.items.insertAt(0, { id: '2', name: '', price: 0 });
+model.items.removeAt(index);
+model.items.move(from, to);
+model.items.swap(a, b);
+model.items.clear();
+model.items.length;                                  // реактивная длина
+model.items.at(0);                                   // под-модель элемента (FormModel<Item>)
+model.items.map((item, i) => item.name);             // item — FormModel<Item>
+```
+
+> **Плоские значения при push.** В `push`/`insertAt` передавай payload из **плоских значений**
+> (`{ id, name, price }`), а НЕ FieldConfig-шаблон (`{ value, component }`). Component/componentProps
+> берутся из `item`-фабрики схемы автоматически.
+
+> **Очистка массива в behavior.** Тот же `model.<array>.clear()` (см. список операций выше) —
+> способ очистить коллекцию **вне React**, из behavior: он мутирует модель напрямую, минуя ноды
+> формы. Типичный случай — сбросить массив при выключении флага:
+>
+> ```typescript
+> onChange(model.$.hasProperty, (on) => {
+>   if (!on) model.properties.clear();
+> });
+> ```
+
+### Rendering Arrays
+
+Каждый элемент массива — под-форма (`FormProxy<Item>`). Итерируй через `form.items.map`:
+
+```tsx
+import { useArrayLength } from '@reformer/core';
+
+function ItemsList({ form }: { form: FormProxy<MyForm> }) {
+  const length = useArrayLength(form.items);
+
+  return (
+    <div>
+      {form.items.map((item, index) => (
+        <div key={index}>
+          <FormField control={item.name} />
+          <FormField control={item.price} />
+          <button onClick={() => model.items.removeAt(index)}>Remove</button>
+        </div>
+      ))}
+
+      {length === 0 && <p>No items yet</p>}
+
+      <button onClick={() => model.items.push({ id: crypto.randomUUID(), name: '', price: 0 })}>
+        Add Item
+      </button>
+    </div>
+  );
+}
+```
+
+> В монорепо для массивов используется готовый `FormArraySection` из `@reformer/ui-kit`
+> (`control={form.items}`, `itemComponent`, `initialValue`, add/remove/reorder из коробки).
+> См. `find_recipe(topic="form-array")`.
+
+### Array Cross-Validation
+
+Whole-array правило пишется оператором `cross(sig, (f) => ...)`: `f` — снапшот `model.get()`
+(плоские значения), ошибка вешается на поле-носитель `sig`. Per-item правила — `each`
+(см. выше, оба — из `@reformer/core/validation`).
+
+Носитель — любое **скалярное** поле формы (флаг `hasItems`, итоговая сумма и т.п.), у которого
+есть сигнал `model.$.<field>` и нода в форме:
+
+```typescript
+import { cross } from '@reformer/core/validation';
+
+type MyForm = { hasItems: boolean; items: Item[] };
+
+// внутри defineValidationSchema<MyForm>(({ model }) => { ... })
+cross(model.$.hasItems, (f: MyForm) => {
+  const names = f.items.map((i) => i.name);
+  return names.length !== new Set(names).size
+    ? { code: 'duplicate', message: 'Item names must be unique' }
+    : null;
+});
+```
+
+## See also
+
+- [03-api-signatures.md](./03-api-signatures.md) — сигнатуры нод `form.<array>` / `ModelArray`, per-item валидация `each`
+- CDK / ui-kit form-array (`FormArray.Root`, `FormArraySection`) — `find_recipe(topic="form-array")`

package/docs/llms/11-async-watchfield.md

@@ -0,0 +1,53 @@
+## 10. ASYNC REACTION — onChange (CRITICALLY IMPORTANT)
+
+Для async-реакции на изменение поля (загрузка зависимых опций, справочников) используй
+`onChange` из `@reformer/core/behaviors`. Колбэк выполняется ВНЕ effect-контекста (можно
+безопасно писать сигналы/ноды), а 2-й аргумент — `{ signal }` (AbortSignal): при следующей
+смене значения предыдущий вызов аннулируется — передавай `signal` в `fetch`.
+
+```typescript
+import { defineFormBehavior, onChange } from '@reformer/core/behaviors';
+
+const behavior = defineFormBehavior<MyForm>(({ model, form }) => {
+  // CORRECT — async onChange со всеми safeguards
+  onChange(
+    model.$.parentField,
+    async (value, { signal }) => {
+      if (!value) {
+        form.dependentField.updateComponentProps({ options: [] });
+        return;
+      }
+      try {
+        const data = await fetchData(value, { signal }); // отмена устаревших запросов
+        form.dependentField.updateComponentProps({ options: data });
+      } catch (error) {
+        if ((error as Error).name === 'AbortError') return;
+        form.dependentField.updateComponentProps({ options: [] });
+      }
+    },
+    { debounce: 300 } // не fetch на каждое нажатие
+  );
+});
+```
+
+### Опции onChange
+
+- `debounce: 300` — не дёргать сеть на каждый keystroke (300–500 мс рекомендуется).
+- `immediate: true` — вызвать колбэк сразу при регистрации (по умолчанию `false`).
+- Guard-clause — пропустить пустое значение.
+- try/catch + проверка `AbortError` — обработка отмены и ошибок.
+
+### Низкоуровневый примитив watchField
+
+`watchField` из `@reformer/core` — базовая подписка на изменение сигнала (без debounce и
+AbortSignal). `onChange` построен поверх него. Для простых синхронных реакций:
+
+```typescript
+import { watchField } from '@reformer/core';
+
+// вызывается при каждом изменении (по умолчанию НЕ на инициализации)
+const stop = watchField(model.$.country, (country) => {
+  model.city = ''; // сброс зависимого поля
+});
+// stop() — отписаться
+```

package/docs/llms/12-array-cleanup.md

@@ -0,0 +1,31 @@
+## 11. ARRAY CLEANUP PATTERN
+
+Очистка массива при выключении флага — через `onChange` на сигнале флага + `clear()` на
+модели-массиве. Колбит выполняется вне effect-контекста, поэтому мутировать массив безопасно.
+
+```typescript
+import { defineFormBehavior, onChange } from '@reformer/core/behaviors';
+
+const behavior = defineFormBehavior<MyForm>(({ model }) => {
+  // при снятии флага — очистить массив
+  onChange(model.$.hasItems, (hasItems) => {
+    if (!hasItems) model.items.clear();
+  });
+});
+```
+
+Переиспользуемый оператор (как в монорепо):
+
+```typescript
+import { onChange } from '@reformer/core/behaviors';
+import type { ReadonlySignal } from '@reformer/core/behaviors';
+
+function clearWhenOff(flag: ReadonlySignal<boolean>, array: { clear(): void }): void {
+  onChange(flag, (on) => {
+    if (!on) array.clear();
+  });
+}
+
+// в схеме поведения:
+clearWhenOff(model.$.hasProperty, model.properties);
+```

package/docs/llms/13-multi-step.md

@@ -0,0 +1,91 @@
+## 12. MULTI-STEP FORM VALIDATION
+
+Каждый шаг — своя `ValidationSchema<Form>` (обычная функция `({ model }) => void`, обёрнутая
+`defineValidationSchema`). Переход к следующему шагу проверяется `validateModel(model, stepSchema)`;
+полный submit — по общей схеме (композиция шагов через `apply(...)`). `validateModel` сам разносит
+ошибки по нодам формы (`getNodeForSignal(sig).setErrors(...)`), поэтому UI подсветит проблемные поля
+текущего шага автоматически. Валидация живёт ОТДЕЛЬНО от layout: сам `RenderNode`/JSON-узел валидаторов
+не несёт — схема инъектируется в рантайме и роутит ошибки по тем же нодам.
+
+```typescript
+import { type FormModel } from '@reformer/core';
+import {
+  validate,
+  apply,
+  defineValidationSchema,
+  validateModel,
+  type ValidationSchema,
+} from '@reformer/core/validation';
+import { required, min } from '@reformer/core/validators';
+
+// Под-схема шага — обычная функция ({ model }) => void. Значения проверяет оператор validate(sig, [rules]).
+const step1Schema = defineValidationSchema<Form>(({ model }) => {
+  validate(model.$.loanType, [required()]);
+  validate(model.$.loanAmount, [required(), min(50000)]);
+});
+
+const step2Schema = defineValidationSchema<Form>(({ model }) => {
+  validate(model.$.personalData.firstName, [required()]);
+  validate(model.$.personalData.lastName, [required()]);
+});
+
+// Карта шагов + полная схема (композиция под-схем через apply — заменяет пошаговую группировку деревом)
+const STEP_SCHEMAS: readonly ValidationSchema<Form>[] = [step1Schema, step2Schema];
+const fullSchema = defineValidationSchema<Form>(() => apply(...STEP_SCHEMAS));
+```
+
+```typescript
+// Переход к следующему шагу. validateModel возвращает Promise<boolean> (true = нет блокирующих ошибок;
+// severity:'warning' не блокирует). Устаревшие прогоны той же (model, schema) отменяются автоматически.
+const goToNextStep = async () => {
+  const ok = await validateModel(model, STEP_SCHEMAS[currentStep - 1]);
+  if (!ok) return; // ошибки уже проставлены в ноды текущего шага
+  setCurrentStep(currentStep + 1);
+};
+
+// Полный submit — по общей схеме
+const handleSubmit = async () => {
+  const ok = await validateModel(model, fullSchema);
+  if (ok) {
+    await onSubmit(model.get());
+  }
+};
+```
+
+Слой-потребитель (`FormWizard`) обычно оборачивает это в конфиг с per-step и полной валидацией:
+
+```typescript
+function makeValidationConfig(model: FormModel<Form>) {
+  return {
+    validateStep: (n: number): Promise<boolean> => validateModel(model, STEP_SCHEMAS[n - 1]),
+    validateAll: (): Promise<boolean> => validateModel(model, fullSchema),
+  };
+}
+```
+
+### Multi-Step Component Example
+
+```tsx
+function MultiStepForm() {
+  const [step, setStep] = useState(1);
+
+  const nextStep = async () => {
+    const ok = await validateModel(model, STEP_SCHEMAS[step - 1]);
+    if (ok) setStep(step + 1);
+  };
+
+  return (
+    <div>
+      {step === 1 && <Step1Fields form={form} />}
+      {step === 2 && <Step2Fields form={form} />}
+
+      <button onClick={() => setStep(step - 1)} disabled={step === 1}>
+        Back
+      </button>
+      <button onClick={step === 2 ? handleSubmit : nextStep}>
+        {step === 2 ? 'Submit' : 'Next'}
+      </button>
+    </div>
+  );
+}
+```