@reformer/core 10.1.0 → 11.0.0-beta.1

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);
+```

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

@@ -0,0 +1,143 @@
+## 1.5 QUICK START - Minimal Working Form
+
+> **Schema-driven UI rule (read first)**: компонент И его пропсы (label, placeholder,
+> options, type) объявляются в **схеме поля** (`component` + `componentProps`).
+> В JSX рендерится один универсальный `<FormField control={form.x} />` из
+> `@reformer/ui-kit` БЕЗ дополнительных props. Не пиши свои `Input`/`Select`/
+> `Checkbox`-обёртки с `label`-prop'ами — это anti-pattern. См.
+> `find_recipe(package="@reformer/ui-kit", topic="form-field-integration")`.
+
+Архитектура M1: сначала создаётся **модель данных** (`createModel`), затем **форма**
+(`createForm({ model, schema })`), где схема привязывает поля к сигналам модели
+(`model.$.field`). Layout-схема НЕ несёт валидаторов — валидация живёт в отдельной
+схеме `defineValidationSchema` из `@reformer/core/validation` и запускается внешним
+раннером `validateModel(model, schema)`.
+
+```typescript
+import { createModel, createForm, 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';
+
+// 1. Define form type as `type` alias (not `interface` — see Recipe 2)
+type ContactForm = {
+  name: string;
+  email: string;
+};
+
+// 2. Model (источник истины значений)
+const model = createModel<ContactForm>({ name: '', email: '' });
+
+// 3. Layout-schema: привязка поля к сигналу (model.$.field) + component/componentProps.
+//    БЕЗ validators — валидация в отдельной схеме (шаг 4).
+const schema = {
+  name: {
+    value: model.$.name,
+    component: Input,
+    componentProps: { label: 'Name', placeholder: 'Your name' },
+  },
+  email: {
+    value: model.$.email,
+    component: Input,
+    componentProps: { label: 'Email', type: 'email' },
+  },
+};
+
+// 4. Validation-schema — отдельный слой (@reformer/core/validation)
+const contactValidation = defineValidationSchema<ContactForm>(({ model }) => {
+  validate(model.$.name, [required({ message: 'Name is required' })]);
+  validate(model.$.email, [required({ message: 'Email is required' }), email({ message: 'Invalid email' })]);
+});
+
+// 5. Form — ноды поверх сигналов модели
+const form = createForm<ContactForm>({ model, schema });
+
+// 6. Use in React component — thin JSX, FormField does ALL heavy lifting
+function ContactFormComponent() {
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    // form.submit()/validate() НЕ гоняют schema-валидацию — только внешний validateModel
+    const ok = await validateModel(model, contactValidation); // Promise<boolean>, ошибки сам роутит в ноды
+    if (ok) {
+      console.log('Form submitted:', model.get());
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <FormField control={form.name} testId="name" />
+      <FormField control={form.email} testId="email" />
+      <Button type="submit">Send</Button>
+    </form>
+  );
+}
+
+// 7. Pass form to child components via props (NOT context!)
+type FormStepProps = {
+  form: FormProxy<ContactForm>;
+};
+
+function FormStep({ form }: FormStepProps) {
+  return <FormField control={form.name} testId="name" />;
+}
+```
+
+> **Стабильность инстанса.** В React создавай model/schema/form ОДИН раз через `useMemo(() => { … }, [])`
+> — иначе форма пересоздаётся на каждый рендер. См. `28-submit-and-reset.md`, `29-async-preload.md`.
+
+### Arrays of objects — `{ array, item }` schema node
+
+Массивы объектов принадлежат модели (`model.arrayField`). В схеме объявляются узлом
+`{ array: model.<path>, item: (itemModel) => itemSchema }`, где `item` строит под-схему
+для каждого элемента из его под-модели (`FormModel<Item>`):
+
+```typescript
+type PropertyItem = {
+  type: 'apartment' | 'house';
+  description: string;
+  estimatedValue: number;
+};
+
+type MyForm = { properties: PropertyItem[] };
+
+const model = createModel<MyForm>({ properties: [] });
+
+// под-схема одного элемента: item.$.field — сигнал под-модели элемента
+const propertyItem = (item: FormModel<PropertyItem>) => ({
+  type: {
+    value: item.$.type,
+    component: Select,
+    componentProps: { label: 'Тип', options: [/* ... */] },
+  },
+  description: { value: item.$.description, component: Textarea, componentProps: { label: 'Описание' } },
+  estimatedValue: {
+    value: item.$.estimatedValue,
+    component: Input,
+    componentProps: { label: 'Стоимость', type: 'number' },
+  },
+});
+
+const schema = {
+  properties: { array: model.properties, item: propertyItem },
+};
+
+const form = createForm<MyForm>({ model, schema });
+
+// Операции над массивом — на модели:
+model.properties.push({ type: 'apartment', description: '', estimatedValue: 0 });
+model.properties.removeAt(0);
+model.properties.length; // реактивная длина
+```
+
+Подробнее в `10-arrays.md`, `21-array-operations.md` и `find_recipe(topic="form-array")`.
+
+### When to write your own field components (advanced — rare)
+
+Свои компоненты нужны ТОЛЬКО если:
+
+- ты намеренно избегаешь `@reformer/ui-kit` (например, проект уже имеет свою design system)
+- нужен особый низкоуровневый input, который не покрывается `FormField` + `componentProps`
+
+В этом случае см. секцию `## 14.5 UI COMPONENT PATTERNS` ниже — но даже там
+паттерн **schema-driven** (label/options не из JSX-props, а из `componentProps` через
+`useFormControl(...).componentProps`).