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

package/dist/state/form-model.d.ts

@@ -1,4 +1,18 @@
 import { FormModel, PathAwareSignal } from './types';
+/**
+ * Узел дерева `model.$` — контейнер (группа/массив), а не лист?
+ *
+ * Контейнерный узел структурно совместим с `ReadonlySignal` (`peek`/`value`/`subscribe`), поэтому
+ * duck-typing «есть `peek` ⇒ это лист» на нём даёт ложное срабатывание. Этот guard — надёжный
+ * способ различить: обходчикам дерева нужно спускаться в контейнер, а не читать его целиком.
+ *
+ * @group Model
+ * @example
+ * ```typescript
+ * const isLeaf = (v: unknown) => isSignalLike(v) && !isModelContainerSignal(v);
+ * ```
+ */
+export declare function isModelContainerSignal(value: unknown): boolean;
 /**
  * Обойти ВСЕ листовые сигналы модели (включая элементы массивов), вызвав `visit` на каждом.
  *

package/dist/state/index.d.ts

@@ -23,7 +23,8 @@
  * @module state
  */
 export { createModel } from './form-model';
-export type { FormModel, ModelArray, ModelObject, ModelValue, ModelSignals, ModelApi, PathAwareSignal, } from './types';
+export type { FormModel, ModelArray, ModelArraySignals, ModelGroupSignals, ModelObject, ModelValue, ModelSignals, ModelApi, PathAwareSignal, } from './types';
+export { isModelContainerSignal } from './form-model';
 export { computeFrom, copyFrom, watchField, transformValue, resetWhen, syncFields, revalidateWhen, } from './behaviors-value';
 export type { BehaviorCleanup } from './behaviors-value';
 export { markDerived, isDerived, unmarkDerived } from './derived-registry';

package/dist/state/types.d.ts

@@ -1,4 +1,4 @@
-import { Signal } from '@preact/signals-core';
+import { ReadonlySignal, Signal } from '@preact/signals-core';
 /**
  * Сигнал, который знает свой путь в модели (`'personalData.lastName'`).
  * Используется как «ручка поля»: и привязка value в схеме, и идентичность для testId/devtools.
@@ -81,8 +81,8 @@ export interface ModelArray<U> {
     [index: number]: ModelValue<U>;
 }
 /**
- * Дерево сигналов (escape-hatch `model.$`): листья → {@link PathAwareSignal},
- * объекты → вложенное дерево, массивы → индексируемое дерево под-сигналов.
+ * Карта под-сигналов объекта в дереве `model.$` (без свойств самого узла — их добавляет
+ * {@link ModelGroupSignals}).
  *
  * @group Model
  */
@@ -90,16 +90,41 @@ export type ModelSignals<T> = {
     [K in keyof T]: ModelSignalNode<T[K]>;
 };
 /**
- * Узел дерева сигналов `model.$`: массив → индексируемый узел под-сигналов, Opaque (Date/File/Blob)
- * и примитив → {@link PathAwareSignal}, объект → вложенное дерево {@link ModelSignals}. Для примитивных
- * и Opaque массивов элемент — сам сигнал листа (а не под-дерево), поэтому `model.$.tags[0]` — это
- * `PathAwareSignal<string>`, а не `ModelSignals<never>`.
+ * Свойства контейнерного узла дерева `$`, «поверх» карты детей. Ключи детей вырезаются из
+ * {@link ReadonlySignal}: доступ к полю формы всегда выигрывает у одноимённого свойства сигнала
+ * (так же ведёт себя рантайм), поэтому `{ value: string }` не порождает конфликта типов.
  * @internal
  */
-type ModelSignalNode<V> = NonNullable<V> extends ReadonlyArray<infer U> ? {
+type ContainerSignal<T, TKeys extends PropertyKey> = Omit<ReadonlySignal<T>, TKeys>;
+/**
+ * Узел-группа дерева `model.$`: доступ к под-сигналам полей ({@link ModelSignals}) И одновременно
+ * {@link ReadonlySignal} агрегированного значения группы — `.value`/`.peek()`/`.subscribe()`.
+ *
+ * ⚠️ Поле формы с именем `value`/`peek`/`subscribe`/`valueOf`/`toString`/`toJSON`/`brand` затеняет
+ * одноимённое свойство сигнала (редкий краевой случай); `subscribe` при этом продолжает работать.
+ *
+ * @group Model
+ */
+export type ModelGroupSignals<T> = ModelSignals<T> & ContainerSignal<T, keyof T>;
+/**
+ * Узел-массив дерева `model.$`: индексируемый доступ к под-сигналам элементов, реактивная `length`
+ * и {@link ReadonlySignal} значения массива целиком (реагирует и на правку элемента, и на изменение
+ * состава — push/removeAt/move).
+ *
+ * @group Model
+ */
+export type ModelArraySignals<U, V> = ContainerSignal<V, 'length'> & {
     readonly length: number;
     readonly [index: number]: ModelSignalNode<U>;
-} : NonNullable<V> extends Opaque ? PathAwareSignal<V> : NonNullable<V> extends object ? ModelSignals<NonNullable<V>> : PathAwareSignal<V>;
+};
+/**
+ * Узел дерева сигналов `model.$`: массив → {@link ModelArraySignals}, Opaque (Date/File/Blob)
+ * и примитив → {@link PathAwareSignal}, объект → {@link ModelGroupSignals}. Для примитивных
+ * и Opaque массивов элемент — сам сигнал листа (а не под-дерево), поэтому `model.$.tags[0]` — это
+ * `PathAwareSignal<string>`, а не `ModelGroupSignals<never>`.
+ * @internal
+ */
+type ModelSignalNode<V> = NonNullable<V> extends ReadonlyArray<infer U> ? ModelArraySignals<U, NonNullable<V>> : NonNullable<V> extends Opaque ? PathAwareSignal<V> : NonNullable<V> extends object ? ModelGroupSignals<NonNullable<V>> : PathAwareSignal<V>;
 /**
  * API уровня модели (доступно на корне, под-моделях вложенных объектов-групп и элементов массива).
  *
@@ -109,8 +134,11 @@ type ModelSignalNode<V> = NonNullable<V> extends ReadonlyArray<infer U> ? {
  * @group Model
  */
 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;
     /**

package/dist/state.js

@@ -1,21 +1,21 @@
-import { c as s } from "./form-model-DYCzGGKF.js";
-import { c as o, a as t, r as c, b as i, d as m, e as d, f, s as l, t as n, w as u } from "./behaviors-value-C7dSEhCc.js";
-import { i as b, m as k, u as v } from "./derived-registry-CluZCQ7U.js";
-import { S as D } from "./subscription-manager-705bls97.js";
+import { c as s, a as r, i as o, m as i, u as t } from "./form-model-DhW2HZOB.js";
+import { c as n, a as d, r as l, b as m, d as f, e as u, f as p, s as b, t as k, w as v } from "./behaviors-value-C7dSEhCc.js";
+import { S as F } from "./subscription-manager-705bls97.js";
 export {
-  D as SubscriptionManager,
-  o as computeFrom,
-  t as copyFrom,
+  F as SubscriptionManager,
+  n as computeFrom,
+  d as copyFrom,
   s as createModel,
-  b as isDerived,
-  k as markDerived,
-  c as resetWhen,
-  i as revalidateWhen,
-  m as runOutsideEffect,
-  d as safeCallback,
-  f as safeDebouncedCallback,
-  l as syncFields,
-  n as transformValue,
-  v as unmarkDerived,
-  u as watchField
+  r as isDerived,
+  o as isModelContainerSignal,
+  i as markDerived,
+  l as resetWhen,
+  m as revalidateWhen,
+  f as runOutsideEffect,
+  u as safeCallback,
+  p as safeDebouncedCallback,
+  b as syncFields,
+  k as transformValue,
+  t as unmarkDerived,
+  v as watchField
 };

package/dist/validation.js

@@ -1,6 +1,54 @@
-import { signal as M, effect as E } from "@preact/signals-core";
-import { e as L } from "./form-model-DYCzGGKF.js";
+import { signal as A, effect as M } from "@preact/signals-core";
+import { e as E } from "./form-model-DhW2HZOB.js";
 import { g as p } from "./signal-node-registry-tiwel-TV.js";
+function B(e, n, t = {}) {
+  const { strategy: r = "submit", debounce: o = 0, liveAfterSubmit: i = "change" } = t, s = A(!1);
+  let a = 0, c = !1, d, l;
+  const w = async (u) => {
+    a++, s.value = !0;
+    try {
+      return await W(e, n, { touch: u });
+    } finally {
+      --a === 0 && (s.value = !1);
+    }
+  }, h = () => {
+    w(!1);
+  }, F = () => {
+    if (!o) {
+      h();
+      return;
+    }
+    l && clearTimeout(l), l = setTimeout(h, o);
+  }, k = (u, g) => {
+    let S = !0;
+    return M(() => {
+      if (E(e, u), S) {
+        S = !1;
+        return;
+      }
+      r === "afterFirstSubmit" && !c || g();
+    });
+  }, m = {
+    async validate() {
+      return c = !0, w(!0);
+    },
+    start() {
+      if (d) return () => m.dispose();
+      const u = r === "afterFirstSubmit" ? i : r;
+      return u === "change" ? d = k((g) => void g.value, F) : u === "blur" && (d = k((g) => void p(g)?.touched.value, h)), () => m.dispose();
+    },
+    dispose() {
+      l && (clearTimeout(l), l = void 0), d?.(), d = void 0;
+    },
+    get isValidating() {
+      return s.value;
+    },
+    get validating() {
+      return s;
+    }
+  };
+  return m;
+}
 let v = null;
 function f(e) {
   if (!v)
@@ -9,83 +57,83 @@ function f(e) {
     );
   return v;
 }
-function b(e, r) {
-  let t = e.errors.get(r);
-  return t || e.errors.set(r, t = []), t;
+function b(e, n) {
+  let t = e.errors.get(n);
+  return t || e.errors.set(n, t = []), t;
 }
-const y = (e) => e.whenStack.every((r) => r());
-function D(e, r) {
-  const t = f("validate"), n = b(t, e);
+const y = (e) => e.whenStack.every((n) => n());
+function D(e, n) {
+  const t = f("validate"), r = b(t, e);
   if (!y(t)) return;
   const o = e.peek();
-  for (const i of r) {
+  for (const i of n) {
     const s = i(o, t.model, t.model);
-    s && n.push(s);
+    s && r.push(s);
   }
 }
-function N(e, r) {
-  const t = f("validateAsync"), n = b(t, e);
+function N(e, n) {
+  const t = f("validateAsync"), r = b(t, e);
   if (!y(t)) return;
   const o = e.peek(), i = t.signal;
-  for (const s of r)
+  for (const s of n)
     t.pending.push(
       s(o, { signal: i }).then(
         (a) => {
-          a && !i.aborted && n.push(a);
+          a && !i.aborted && r.push(a);
         },
         () => {
         }
       )
     );
 }
-function R(e, r) {
+function R(e, n) {
   const t = f("validateWhen");
   t.whenStack.push(e);
   try {
-    r();
+    n();
   } finally {
     t.whenStack.pop();
   }
 }
-function _(e, r) {
-  const t = f("cross"), n = b(t, e);
+function _(e, n) {
+  const t = f("cross"), r = b(t, e);
   if (!y(t)) return;
-  const o = r(t.model.get());
-  o && n.push(o);
+  const o = n(t.model.get());
+  o && r.push(o);
 }
-function $(e, r) {
+function $(e, n) {
   f("each");
   const t = e.length;
-  for (let n = 0; n < t; n++) r(e.at(n));
+  for (let r = 0; r < t; r++) n(e.at(r));
 }
 function j(...e) {
   const t = f("apply").model;
-  for (const n of e) n({ model: t });
+  for (const r of e) r({ model: t });
 }
 function z(e) {
   return e;
 }
-const F = /* @__PURE__ */ new WeakMap();
-function P(e, r) {
-  let t = F.get(e);
-  t || F.set(e, t = /* @__PURE__ */ new WeakMap());
-  let n = t.get(r);
-  return n || t.set(r, n = { fields: /* @__PURE__ */ new Set(), ac: null }), n;
+const x = /* @__PURE__ */ new WeakMap();
+function L(e, n) {
+  let t = x.get(e);
+  t || x.set(e, t = /* @__PURE__ */ new WeakMap());
+  let r = t.get(n);
+  return r || t.set(n, r = { fields: /* @__PURE__ */ new Set(), ac: null }), r;
 }
-const T = (e) => {
-  for (const r of e.values()) for (const t of r) if (t.severity !== "warning") return !0;
+const P = (e) => {
+  for (const n of e.values()) for (const t of n) if (t.severity !== "warning") return !0;
   return !1;
 };
-function W(e) {
-  return e.aborted ? Promise.resolve() : new Promise((r) => {
-    e.addEventListener("abort", () => r(), { once: !0 });
+function T(e) {
+  return e.aborted ? Promise.resolve() : new Promise((n) => {
+    e.addEventListener("abort", () => n(), { once: !0 });
   });
 }
-async function V(e, r, t) {
-  const n = P(e, r);
-  n.ac?.abort();
+async function W(e, n, t) {
+  const r = L(e, n);
+  r.ac?.abort();
   const o = new AbortController();
-  n.ac = o;
+  r.ac = o;
   const i = {
     model: e,
     errors: /* @__PURE__ */ new Map(),
@@ -95,73 +143,25 @@ async function V(e, r, t) {
   }, s = v;
   v = i;
   try {
-    r({ model: e });
+    n({ model: e });
   } finally {
     v = s;
   }
-  if (i.pending.length && await Promise.race([Promise.all(i.pending), W(o.signal)]), o.signal.aborted) return !1;
+  if (i.pending.length && await Promise.race([Promise.all(i.pending), T(o.signal)]), o.signal.aborted) return !1;
   const a = new Set(i.errors.keys());
-  for (const c of n.fields) a.has(c) || p(c)?.setErrors([]);
+  for (const c of r.fields) a.has(c) || p(c)?.setErrors([]);
   for (const c of a) p(c)?.setErrors(i.errors.get(c) ?? []);
   if (t?.touch) for (const c of a) p(c)?.markAsTouched();
-  return n.fields = a, !T(i.errors);
-}
-function G(e, r, t = {}) {
-  const { strategy: n = "submit", debounce: o = 0, liveAfterSubmit: i = "change" } = t, s = M(!1);
-  let a = 0, c = !1, w = !1, d, l;
-  const k = async (u) => {
-    a++, s.value = !0;
-    try {
-      return await V(e, r, { touch: u });
-    } finally {
-      --a === 0 && (s.value = !1);
-    }
-  }, h = () => {
-    k(!1);
-  }, A = () => {
-    if (!o) {
-      h();
-      return;
-    }
-    l && clearTimeout(l), l = setTimeout(h, o);
-  }, S = (u, g) => {
-    let x = !0;
-    return E(() => {
-      if (L(e, u), x) {
-        x = !1;
-        return;
-      }
-      n === "afterFirstSubmit" && !c || g();
-    });
-  }, m = {
-    async validate() {
-      return c = !0, k(!0);
-    },
-    start() {
-      if (w || d) return () => m.dispose();
-      const u = n === "afterFirstSubmit" ? i : n;
-      return u === "change" ? d = S((g) => void g.value, A) : u === "blur" && (d = S((g) => void p(g)?.touched.value, h)), () => m.dispose();
-    },
-    dispose() {
-      w = !0, l && (clearTimeout(l), l = void 0), d?.(), d = void 0;
-    },
-    get isValidating() {
-      return s.value;
-    },
-    get validating() {
-      return s;
-    }
-  };
-  return m;
+  return r.fields = a, !P(i.errors);
 }
 export {
   j as apply,
-  G as createFormValidation,
+  B as createFormValidation,
   _ as cross,
   z as defineValidationSchema,
   $ as each,
   D as validate,
   N as validateAsync,
-  V as validateModel,
+  W as validateModel,
   R as validateWhen
 };

package/docs/llms/02-quick-start.md

@@ -7,14 +7,15 @@
 > `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';
@@ -49,8 +50,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() {
@@ -121,7 +128,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 });

package/docs/llms/15-project-structure.md

@@ -15,7 +15,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 }
@@ -60,11 +60,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)
@@ -90,10 +94,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

package/docs/llms/19-reading-values.md

@@ -29,9 +29,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`) —

package/docs/llms/20-compute-vs-watch.md

@@ -121,6 +121,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 |
@@ -129,6 +137,7 @@ const stop = watchField(model.$.country, () => { model.city = ''; });
 | Производное с явными зависимостями | `computeFrom` |
 | Async-реакция, обновление componentProps | `onChange` (debounce + AbortSignal) |
 | Простая синхронная реакция (примитив) | `watchField` |
+| Реакция на любое изменение группы/формы | `watchField(model.$.<группа>)` или `.subscribe` |
 
 ### Chained computeds