@reformer/core 10.2.0 → 11.0.0-beta.2

package/dist/runtime-token.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Штамп копии рантайма ядра.
+ *
+ * Единственное назначение — быть объектом, уникальным в пределах ОДНОЙ копии модуля. Две
+ * независимо загруженные копии `@reformer/core` дадут два разных объекта, и по их несовпадению
+ * guard распознаёт дубль рантайма.
+ *
+ * Почему именно объект, а не строка с версией: две копии ОДНОЙ версии ломают всё ровно так же,
+ * как две копии разных версий, — раздваиваются модульные `WeakMap` (`derived-registry`,
+ * `signal-node-registry`) и перестают работать проверки `instanceof Signal`. Сравнение версий
+ * такой случай пропустило бы.
+ *
+ * @see `@reformer/form-registry/guard`
+ *
+ * @example
+ * ```ts
+ * import { CORE_RUNTIME_TOKEN } from '@reformer/core';
+ * import { stampRuntime } from '@reformer/form-registry/guard';
+ *
+ * stampRuntime('@reformer/core', CORE_RUNTIME_TOKEN);
+ * ```
+ */
+export declare const CORE_RUNTIME_TOKEN: object;

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,5 +1,5 @@
 import { signal as M, effect as E } from "@preact/signals-core";
-import { e as L } from "./form-model-DYCzGGKF.js";
+import { e as L } from "./form-model-DhW2HZOB.js";
 import { g as p } from "./signal-node-registry-tiwel-TV.js";
 let v = null;
 function f(e) {

package/dist/validators.d.ts

@@ -1,6 +1,2 @@
 export * from './form/validators'
 export {}
-import _default from './form/validators'
-export default _default
-export * from './form/validators'
-export {}

package/dist/validators.js

@@ -1,200 +1,166 @@
-import { required as u } from "./validators/required.js";
-import { min as a } from "./validators/min.js";
-import { max as p } from "./validators/max.js";
-import { minLength as c } from "./validators/min-length.js";
-import { maxLength as g } from "./validators/max-length.js";
-import { email as d } from "./validators/email.js";
-import { pattern as z } from "./validators/pattern.js";
-import { url as h } from "./validators/url.js";
-import { phone as y } from "./validators/phone.js";
-import { isNumber as F } from "./validators/is-number.js";
-import { integer as x } from "./validators/integer.js";
-import { multipleOf as S } from "./validators/multiple-of.js";
-import { nonNegative as b } from "./validators/non-negative.js";
-import { nonZero as A } from "./validators/non-zero.js";
-import { isDate as L } from "./validators/is-date.js";
-import { minDate as T } from "./validators/min-date.js";
-import { maxDate as C } from "./validators/max-date.js";
-import { pastDate as D } from "./validators/past-date.js";
-import { futureDate as N } from "./validators/future-date.js";
-import { minAge as W } from "./validators/min-age.js";
-import { maxAge as _ } from "./validators/max-age.js";
-function m(r) {
+import { required as z } from "./validators/required.js";
+import { min as y } from "./validators/min.js";
+import { max as b } from "./validators/max.js";
+import { minLength as L } from "./validators/min-length.js";
+import { maxLength as D } from "./validators/max-length.js";
+import { email as T } from "./validators/email.js";
+import { pattern as w } from "./validators/pattern.js";
+import { url as k } from "./validators/url.js";
+import { phone as B } from "./validators/phone.js";
+import { isNumber as Z } from "./validators/is-number.js";
+import { integer as G } from "./validators/integer.js";
+import { multipleOf as I } from "./validators/multiple-of.js";
+import { nonNegative as K } from "./validators/non-negative.js";
+import { nonZero as P } from "./validators/non-zero.js";
+import { isDate as R } from "./validators/is-date.js";
+import { minDate as V } from "./validators/min-date.js";
+import { maxDate as Y } from "./validators/max-date.js";
+import { pastDate as $ } from "./validators/past-date.js";
+import { futureDate as ee } from "./validators/future-date.js";
+import { minAge as ne } from "./validators/min-age.js";
+import { maxAge as ie } from "./validators/max-age.js";
+function s(r) {
   if (typeof r != "object" || r === null) return !1;
-  const i = r;
-  return !(typeof i.name != "string" || i.size !== void 0 && typeof i.size != "number" || i.type !== void 0 && typeof i.type != "string");
+  const t = r;
+  return !(typeof t.name != "string" || t.size !== void 0 && typeof t.size != "number" || t.type !== void 0 && typeof t.type != "string");
 }
 function o(r) {
-  return Array.isArray(r) ? r.filter(m) : m(r) ? [r] : null;
+  return Array.isArray(r) ? r.filter(s) : s(r) ? [r] : null;
 }
-function s(r, i) {
-  const e = i.split(",").map((l) => l.trim().toLowerCase()).filter(Boolean);
+function u(r, t) {
+  const e = t.split(",").map((l) => l.trim().toLowerCase()).filter(Boolean);
   if (e.length === 0) return !0;
-  const n = r.name.toLowerCase(), t = (r.type ?? "").toLowerCase();
-  return e.some((l) => l.startsWith(".") ? n.endsWith(l) : l.endsWith("/*") ? t.startsWith(l.slice(0, -1)) : l.includes("/") ? t === l : !1);
+  const n = r.name.toLowerCase(), i = (r.type ?? "").toLowerCase();
+  return e.some((l) => l.startsWith(".") ? n.endsWith(l) : l.endsWith("/*") ? i.startsWith(l.slice(0, -1)) : l.includes("/") ? i === l : !1);
 }
-function j(r, i) {
+function m(r, t) {
   return (e) => {
     if (e == null || e === "")
       return null;
     const n = o(e);
     if (n === null || n.length === 0) return null;
-    for (const t of n)
-      if (typeof t.size == "number" && t.size > r)
+    for (const i of n)
+      if (typeof i.size == "number" && i.size > r)
         return {
           code: "maxFileSize",
-          message: i?.message ?? "invalid",
+          message: t?.message ?? "invalid",
           params: {
             maxFileSize: r,
-            fileName: t.name,
-            actualSize: t.size,
-            ...i?.params
+            fileName: i.name,
+            actualSize: i.size,
+            ...t?.params
           }
         };
     return null;
   };
 }
-function w(r, i) {
+function a(r, t) {
   return (e) => {
     if (e == null || e === "")
       return null;
     const n = o(e);
     if (n === null || n.length === 0) return null;
-    for (const t of n)
-      if (typeof t.size == "number" && t.size < r)
+    for (const i of n)
+      if (typeof i.size == "number" && i.size < r)
         return {
           code: "minFileSize",
-          message: i?.message ?? "invalid",
+          message: t?.message ?? "invalid",
           params: {
             minFileSize: r,
-            fileName: t.name,
-            actualSize: t.size,
-            ...i?.params
+            fileName: i.name,
+            actualSize: i.size,
+            ...t?.params
           }
         };
     return null;
   };
 }
-function O(r, i) {
+function p(r, t) {
   return (e) => {
     if (e == null || e === "")
       return null;
     const n = o(e);
     if (n === null || n.length === 0) return null;
-    for (const t of n)
-      if (!s(t, r))
+    for (const i of n)
+      if (!u(i, r))
         return {
           code: "fileType",
-          message: i?.message ?? "invalid",
-          params: { accept: r, fileName: t.name, ...i?.params }
+          message: t?.message ?? "invalid",
+          params: { accept: r, fileName: i.name, ...t?.params }
         };
     return null;
   };
 }
-function k(r, i) {
+function c(r, t) {
   return (e) => {
     if (e == null || e === "")
       return null;
     const n = o(e);
     return n === null || n.length === 0 ? null : n.length > r ? {
       code: "maxFiles",
-      message: i?.message ?? "invalid",
-      params: { maxFiles: r, actualCount: n.length, ...i?.params }
+      message: t?.message ?? "invalid",
+      params: { maxFiles: r, actualCount: n.length, ...t?.params }
     } : null;
   };
 }
-function q(r, i) {
+function x(r, t) {
   return (e) => {
     if (e == null || e === "")
       return null;
     const n = o(e);
     return n === null || n.length === 0 ? null : n.length < r ? {
       code: "minFiles",
-      message: i?.message ?? "invalid",
-      params: { minFiles: r, actualCount: n.length, ...i?.params }
+      message: t?.message ?? "invalid",
+      params: { minFiles: r, actualCount: n.length, ...t?.params }
     } : null;
   };
 }
-function B(r, i) {
+function g(r, t) {
   return (e) => {
     if (e == null || e === "")
       return null;
     const n = o(e);
     if (n === null || n.length === 0) return null;
-    const t = n.reduce(
+    const i = n.reduce(
       (l, f) => l + (typeof f.size == "number" ? f.size : 0),
       0
     );
-    return t > r ? {
+    return i > r ? {
       code: "maxTotalFileSize",
-      message: i?.message ?? "invalid",
-      params: { maxTotalFileSize: r, actualTotal: t, ...i?.params }
+      message: t?.message ?? "invalid",
+      params: { maxTotalFileSize: r, actualTotal: i, ...t?.params }
     } : null;
   };
 }
-const te = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
-  __proto__: null,
-  email: d,
-  fileType: O,
-  futureDate: N,
-  integer: x,
-  isDate: L,
-  isFileLike: m,
-  isNumber: F,
-  matchesFileAccept: s,
-  max: p,
-  maxAge: _,
-  maxDate: C,
-  maxFileSize: j,
-  maxFiles: k,
-  maxLength: g,
-  maxTotalFileSize: B,
-  min: a,
-  minAge: W,
-  minDate: T,
-  minFileSize: w,
-  minFiles: q,
-  minLength: c,
-  multipleOf: S,
-  nonNegative: b,
-  nonZero: A,
-  pastDate: D,
-  pattern: z,
-  phone: y,
-  required: u,
-  toFileArray: o,
-  url: h
-}, Symbol.toStringTag, { value: "Module" }));
 export {
-  te as default,
-  d as email,
-  O as fileType,
-  N as futureDate,
-  x as integer,
-  L as isDate,
-  m as isFileLike,
-  F as isNumber,
-  s as matchesFileAccept,
-  p as max,
-  _ as maxAge,
-  C as maxDate,
-  j as maxFileSize,
-  k as maxFiles,
-  g as maxLength,
-  B as maxTotalFileSize,
-  a as min,
-  W as minAge,
-  T as minDate,
-  w as minFileSize,
-  q as minFiles,
-  c as minLength,
-  S as multipleOf,
-  b as nonNegative,
-  A as nonZero,
-  D as pastDate,
-  z as pattern,
-  y as phone,
-  u as required,
+  T as email,
+  p as fileType,
+  ee as futureDate,
+  G as integer,
+  R as isDate,
+  s as isFileLike,
+  Z as isNumber,
+  u as matchesFileAccept,
+  b as max,
+  ie as maxAge,
+  Y as maxDate,
+  m as maxFileSize,
+  c as maxFiles,
+  D as maxLength,
+  g as maxTotalFileSize,
+  y as min,
+  ne as minAge,
+  V as minDate,
+  a as minFileSize,
+  x as minFiles,
+  L as minLength,
+  I as multipleOf,
+  K as nonNegative,
+  P as nonZero,
+  $ as pastDate,
+  w as pattern,
+  B as phone,
+  z as required,
   o as toFileArray,
-  h as url
+  k as url
 };

package/docs/llms/01-api-reference.md

@@ -0,0 +1,63 @@
+## 1. API Reference
+
+### Imports (CRITICALLY IMPORTANT)
+
+Архитектура M1: значения живут в **модели** (`createModel`), а форма (`createForm`) строит ноды поверх сигналов модели. Behaviors работают на сигналах (`model.$.field`), а не на строковых путях.
+
+| What                                                                                                   | Where                       |
+| ------------------------------------------------------------------------------------------------------ | --------------------------- |
+| `createModel`, `createForm`                                                                            | `@reformer/core`            |
+| `validateModel`, `defineValidationSchema`, `validate`, `validateAsync`, `validateWhen`, `cross`, `each`, `apply` | `@reformer/core/validation` |
+| `Rule`, `AsyncRule`, `ValidationSchema` (типы)                                                         | `@reformer/core/validation` |
+| `useFormControl`, `useFormControlValue`, `useArrayLength`                                              | `@reformer/core`            |
+| `FormModel`, `FormProxy`, `FieldNode`, `GroupNode`, `ArrayNode`, `ModelArrayNode`                     | `@reformer/core`            |
+| `ModelSignals`, `ModelArray`, `ModelValue`, `ModelObject`, `PathAwareSignal`                          | `@reformer/core`            |
+| `ValidationError`, `FieldConfig`, `FormSchema`, `FieldControlState`                                    | `@reformer/core`            |
+| `computeFrom`, `copyFrom`, `watchField`, `enableWhen`, `disableWhen`                                   | `@reformer/core` (примитивы) |
+| `transformValue`, `resetWhen`, `syncFields`, `revalidateWhen`                                          | `@reformer/core` (примитивы) |
+| `required`, `min`, `max`, `minLength`, `maxLength`, `email`, `pattern`, `url`, `phone`                | `@reformer/core/validators` |
+| `isNumber`, `integer`, `multipleOf`, `nonNegative`, `nonZero`                                          | `@reformer/core/validators` |
+| `isDate`, `minDate`, `maxDate`, `pastDate`, `futureDate`, `minAge`, `maxAge`                           | `@reformer/core/validators` |
+| `defineFormBehavior`, `compute`, `computeFrom`, `copyFrom`, `onChange`, `enableWhen`, `disableWhen`   | `@reformer/core/behaviors`  |
+| `transformValue`, `resetWhen`, `syncFields`, `revalidateWhen`, `apply`, `applyEach`, `aggregateInto`  | `@reformer/core/behaviors`  |
+| `exclusiveFlag`, `onDispose`, `getScope`, `effect`, `defer`                                            | `@reformer/core/behaviors`  |
+
+> **Два способа писать behaviors.** Низкоуровневые примитивы (`computeFrom`, `copyFrom`, `watchField`,
+> `enableWhen`, …) экспортируются из `@reformer/core`, принимают **сигналы** (`model.$.x`), возвращают
+> **cleanup-функцию** и вызываются императивно (например, в `useEffect`). Декларативный DSL
+> (`defineFormBehavior` + операторы) экспортируется из `@reformer/core/behaviors`, регистрирует cleanup
+> сам и передаётся в `createForm({ behavior })`. См. `20-compute-vs-watch.md`.
+
+> **Валидация — отдельный слой.** Layout-схема `createForm` НЕ несёт валидаторов. Правила живут в
+> `defineValidationSchema<T>(({ model }) => { validate(model.$.x, [required(), min(50000)]); ... })`
+> из `@reformer/core/validation`; фабрики `required()`, `min(50000)`, `email()` возвращают
+> `Rule<T> = (value) => ValidationError | null` и передаются массивом в `validate(sig, [...])`.
+> Запуск — только внешним раннером `await validateModel(model, schema)` (`Promise<boolean>`, ошибки
+> сам роутит в ноды; `form.validate()`/`form.submit()` schema-валидацию НЕ гоняют).
+
+### Type Values
+
+- Опциональные числа: `number | null` (конвенция «пользователь очистил поле»)
+- Опциональные строки: `string` (по умолчанию пустая строка) или `string | null`
+- Form-shape тип объявляй как `type`-alias — см. `30-type-safety-recipes.md`
+
+### React Hooks Comparison (CRITICALLY IMPORTANT)
+
+| Hook | Return Type | Subscribes To | Use Case |
+|------|-------------|---------------|----------|
+| `useFormControl(field)` | `{ value, errors, disabled, touched, valid, invalid, pending, shouldShowError, componentProps }` | Все сигналы поля | Полное состояние поля, инпуты |
+| `useFormControlValue(field)` | `T` (значение напрямую) | Только сигнал value | Условный рендеринг |
+| `useArrayLength(array)` | `number` | Только длина массива | Реактивная длина массива |
+
+**CRITICAL**: Не деструктурируй `useFormControlValue`! Он возвращает `T` напрямую, НЕ `{ value: T }`.
+
+```typescript
+// WRONG - will always be undefined!
+const { value: loanType } = useFormControlValue(control.loanType);
+
+// CORRECT
+const loanType = useFormControlValue(control.loanType);
+
+// CORRECT - useFormControl returns object, destructuring OK
+const { value, errors, disabled } = useFormControl(control.loanType);
+```