@reformer/core 4.0.0 → 5.0.2

package/dist/core/validation/validators/email.d.ts

@@ -34,4 +34,4 @@ import { FieldPathNode } from '../../types';
  * }
  * ```
  */
-export declare function email<TForm, TField extends string | undefined = string>(fieldPath: FieldPathNode<TForm, TField> | undefined, options?: ValidateOptions): void;
+export declare function email<TForm, TField extends string | null | undefined = string>(fieldPath: FieldPathNode<TForm, TField> | undefined, options?: ValidateOptions): void;

package/dist/core/validation/validators/pattern.d.ts

@@ -37,4 +37,4 @@ import { FieldPathNode } from '../../types';
  * }
  * ```
  */
-export declare function pattern<TForm, TField extends string | undefined = string>(fieldPath: FieldPathNode<TForm, TField> | undefined, regex: RegExp, options?: ValidateOptions): void;
+export declare function pattern<TForm, TField extends string | null | undefined = string>(fieldPath: FieldPathNode<TForm, TField> | undefined, regex: RegExp, options?: ValidateOptions): void;

package/dist/core/validation/validators/phone.d.ts

@@ -21,7 +21,7 @@ export type PhoneFormat = 'international' | 'ru' | 'us' | 'any';
  * phone(path.phoneNumber, { format: 'international', message: 'Неверный формат телефона' });
  * ```
  */
-export declare function phone<TForm, TField extends string | undefined = string>(fieldPath: FieldPathNode<TForm, TField> | undefined, options?: ValidateOptions & {
+export declare function phone<TForm, TField extends string | null | undefined = string>(fieldPath: FieldPathNode<TForm, TField> | undefined, options?: ValidateOptions & {
     /** Формат телефона */
     format?: PhoneFormat;
 }): void;

package/dist/core/validation/validators/url.d.ts

@@ -14,7 +14,7 @@ import { FieldPathNode } from '../../types';
  * url(path.website, { requireProtocol: true });
  * ```
  */
-export declare function url<TForm, TField extends string | undefined = string>(fieldPath: FieldPathNode<TForm, TField> | undefined, options?: ValidateOptions & {
+export declare function url<TForm, TField extends string | null | undefined = string>(fieldPath: FieldPathNode<TForm, TField> | undefined, options?: ValidateOptions & {
     /** Требовать наличие протокола (http:// или https://) */
     requireProtocol?: boolean;
     /** Разрешенные протоколы */

package/llms.txt

@@ -34,6 +34,8 @@
 - 28-submit-and-reset.md — Submit и Reset — Жизненный цикл отправки формы
 - 29-async-preload.md — Async Preload — Загрузка начальных значений и динамических справочников
 - 30-type-safety-recipes.md — type-safety-recipes
+- 31-async-validator-debounce.md — async-validator-debounce
+- 32-async-options-loading.md — async-options-loading
 - API Reference (auto-generated from JSDoc)
 
 ## 1. 1. API Reference
@@ -81,23 +83,38 @@ const { value, errors, disabled } = useFormControl(control.loanType);
 
 ## 2. 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")`.
+
 ```typescript
-import { createForm, useFormControl } from '@reformer/core';
+import { createForm, type FormProxy, type FormSchema } from '@reformer/core';
 import { required, email } from '@reformer/core/validators';
-import type { FormProxy } from '@reformer/core';
+import { FormField, Input, Button } from '@reformer/ui-kit';
 
-// 1. Define form type
-interface ContactForm {
+// 1. Define form type as `type` alias (not `interface` — see Recipe 2)
+type ContactForm = {
   name: string;
   email: string;
-}
+};
 
-// 2. Create form schema with validation
+// 2. Schema: component + componentProps decl in fields, no JSX label props
 const form = createForm<ContactForm>({
   form: {
-    name: { value: '', component: Input },
-    email: { value: '', component: Input },
-  },
+    name: {
+      value: '',
+      component: Input,
+      componentProps: { label: 'Name', placeholder: 'Your name' },
+    },
+    email: {
+      value: '',
+      component: Input,
+      componentProps: { label: 'Email', type: 'email' },
+    },
+  } satisfies FormSchema<ContactForm>,
   validation: (path) => {
     required(path.name, { message: 'Name is required' });
     required(path.email, { message: 'Email is required' });
@@ -105,52 +122,68 @@ const form = createForm<ContactForm>({
   },
 });
 
-// 3. Use in React component
+// 3. Use in React component — thin JSX, FormField does ALL heavy lifting
 function ContactFormComponent() {
-  const nameCtrl = useFormControl(form.name);
-  const emailCtrl = useFormControl(form.email);
-
   const handleSubmit = async () => {
-    await form.submit((values) => {
+    await form.submit((values: ContactForm) => {
       console.log('Form submitted:', values);
     });
   };
 
   return (
     <form onSubmit={(e) => { e.preventDefault(); handleSubmit(); }}>
-      <div>
-        <input
-          value={nameCtrl.value}
-          onChange={(e) => form.name.setValue(e.target.value)}
-          disabled={nameCtrl.disabled}
-        />
-        {nameCtrl.errors.map((err) => <span key={err.code}>{err.message}</span>)}
-      </div>
-      <div>
-        <input
-          value={emailCtrl.value}
-          onChange={(e) => form.email.setValue(e.target.value)}
-          disabled={emailCtrl.disabled}
-        />
-        {emailCtrl.errors.map((err) => <span key={err.code}>{err.message}</span>)}
-      </div>
-      <button type="submit">Send</button>
+      <FormField control={form.name} testId="name" />
+      <FormField control={form.email} testId="email" />
+      <Button type="submit">Send</Button>
     </form>
   );
 }
 
 // 4. Pass form to child components via props (NOT context!)
-interface FormStepProps {
+type FormStepProps = {
   form: FormProxy<ContactForm>;
-}
+};
 
 function FormStep({ form }: FormStepProps) {
-  // Access form fields directly
-  const { value } = useFormControl(form.name);
-  return <div>Name: {value}</div>;
+  return <FormField control={form.name} testId="name" />;
 }
 ```
 
+### Arrays of objects — tuple format
+
+⚠️ Массивы объектов в схеме объявляются **через tuple `[itemSchema]`**, НЕ через `FieldConfig` с `value: []`:
+
+```typescript
+// ❌ DON'T — TS error: Type 'FieldConfig<PropertyItem[]>' is not assignable to type '[FormSchema<PropertyItem>]'
+const schema: FormSchema<{ properties: PropertyItem[] }> = {
+  properties: { value: [], component: Input },  // ← intuitive but WRONG
+};
+
+// ✅ DO — tuple [itemSchema]: ArrayNode infers item shape from первого элемента
+const schema: FormSchema<{ properties: PropertyItem[] }> = {
+  properties: [
+    {
+      type: { value: 'apartment', component: Select, componentProps: { ... } } satisfies FieldConfig<PropertyType>,
+      description: { value: '', component: Textarea, componentProps: { label: 'Описание' } },
+      estimatedValue: { value: 0, component: Input, componentProps: { label: 'Стоимость', type: 'number' } },
+    },
+  ],
+};
+```
+
+В runtime массив пуст (`form.properties.value === []`); tuple — это **template** для каждого item, который применяется при `form.properties.push()` / `.insert()`. См. подробности в `find_recipe(topic="form-array")` и `find_recipe(topic="array-operations")`.
+
+### 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`).
+
 ## 3. 2. API SIGNATURES
 
 ### Validators
@@ -497,10 +530,46 @@ const behavior: BehaviorSchemaFn<LoanForm> = (path) => {
 };
 ```
 
-Reference patterns: `complex-multy-step-form/schemas/credit-application-behavior.ts` and `mcp-credit-application-v10/schema.ts` (Compute helpers section).
+Reference patterns: `complex-multy-step-form/schemas/credit-application-behavior.ts`.
 
 ## 6. 4. COMMON MISTAKES
 
+### TSC overload-resolution error: `'form' does not exist in FormSchema<T>`
+
+**Симптом**:
+
+```
+TS2769: Object literal may only specify known properties, and 'form' does not
+exist in type 'FormSchema<MyForm>'.
+```
+
+(или похожее с `validation` / `behavior` ключами).
+
+**Причина**: `createForm` имеет 2 overload — `GroupNodeConfig<T>` (с `form/validation/behavior`)
+и schema-only. Если в inline literal `form: { ... }` есть глубокая inference-проблема
+(чаще всего — literal default value у union-типа поля, см. Recipe 8 в
+[30-type-safety-recipes.md](30-type-safety-recipes.md)), TS отбрасывает Overload 1 и
+матчит Overload 2 (schema-only). В нём ключа `form` нет — получаешь misleading error.
+
+**Workaround** — extract `form` literal в typed local:
+
+```ts
+const form: FormSchema<MyForm> = {
+  fieldA: { value: 'foo', component: Input /* ... */ },
+  // ...
+};
+
+createForm({ form, validation, behavior });
+```
+
+Теперь TS репортит **реальную** per-field ошибку — например:
+
+```
+TS2322: Type '"male"' is not assignable to type 'Gender | null'
+```
+
+После этого решай конкретную проблему (Recipe 8 — `satisfies FieldConfig<UnionType>`).
+
 ### Imports rule (#1 cause of cascading errors — read first)
 
 Types live in `@reformer/core`. Functions live in submodules (`/validators`,
@@ -1286,105 +1355,185 @@ export const creditApplicationValidation: ValidationSchemaFn<Form> = (path) => {
 
 ## 17. 14.5 UI COMPONENT PATTERNS
 
-ReFormer does NOT provide UI components - you create them yourself or use a UI library.
+> **Default rule (read first)**: для UI используй `FormField` из
+> [`@reformer/ui-kit`](../../reformer-ui-kit/) — он покрывает 95% случаев одной
+> строкой `<FormField control={form.x} />`. Свои field-обёртки пиши ТОЛЬКО если
+> ui-kit не подходит (другая design system, особый low-level input).
+>
+> Канонический schema-driven подход:
+>
+> - **компонент** объявляется в схеме как `component: Input` (или `Select`, `Checkbox`, etc.)
+> - **пропсы** компонента — в `componentProps: { label, placeholder, options, type, ... }`
+> - **JSX рендерит**: `<FormField control={form.x} />` БЕЗ дополнительных props
+>
+> См. `find_recipe(package="@reformer/ui-kit", topic="form-field-integration")`
+> для полного руководства.
 
-### Generic FormField Component
+### Default — FormField из ui-kit (canonical)
 
 ```tsx
-import type { FieldNode } from '@reformer/core';
-import { useFormControl } from '@reformer/core';
+import { useMemo } from 'react';
+import { createForm, type FormSchema } from '@reformer/core';
+import { FormField, Input, Select, Checkbox, Button } from '@reformer/ui-kit';
 
-interface FormFieldProps<T> {
-  control: FieldNode<T>;
-  label?: string;
-  type?: 'text' | 'email' | 'number' | 'password';
-  placeholder?: string;
-}
+type RegistrationForm = {
+  email: string;
+  country: string;
+  agree: boolean;
+};
 
-function FormField<T extends string | number>({
-  control,
-  label,
-  type = 'text',
-  placeholder
-}: FormFieldProps<T>) {
-  const { value, errors, disabled, touched } = useFormControl(control);
-  const showError = touched && errors.length > 0;
+function RegistrationPage() {
+  const form = useMemo(
+    () =>
+      createForm<RegistrationForm>({
+        form: {
+          email: {
+            value: '',
+            component: Input,
+            componentProps: { label: 'Email', type: 'email', placeholder: 'you@example.com' },
+          },
+          country: {
+            value: 'ru',
+            component: Select,
+            componentProps: {
+              label: 'Country',
+              options: [
+                { value: 'ru', label: 'Россия' },
+                { value: 'by', label: 'Беларусь' },
+              ],
+            },
+          },
+          agree: {
+            value: false,
+            component: Checkbox,
+            componentProps: { label: 'I agree to terms' },
+          },
+        } satisfies FormSchema<RegistrationForm>,
+      }),
+    []
+  );
 
   return (
-    <div className="form-field">
-      {label && <label>{label}</label>}
-      <input
-        type={type}
-        value={value ?? ''}
-        onChange={(e) => {
-          const val = type === 'number'
-            ? Number(e.target.value) as T
-            : e.target.value as T;
-          control.setValue(val);
-        }}
-        onBlur={() => control.markAsTouched()}
-        disabled={disabled}
-        placeholder={placeholder}
-        className={showError ? 'error' : ''}
-      />
-      {showError && (
-        <span className="error-message">{errors[0].message}</span>
-      )}
-    </div>
+    <form>
+      <FormField control={form.email} testId="email" />
+      <FormField control={form.country} testId="country" />
+      <FormField control={form.agree} testId="agree" />
+      <Button type="submit">Register</Button>
+    </form>
   );
 }
+```
+
+`FormField` сам читает `componentProps.label`, `componentProps.placeholder`,
+`componentProps.options` через `useFormControl(...).componentProps` и применяет
+их к нужному `<input>`/`<select>`/etc. Error rendering, `pending` для async-валидаций,
+`data-testid` для e2e — всё из коробки.
+
+### Anti-patterns (не делай так)
+
+❌ **Свои field-компоненты с label-prop'ами в JSX**:
 
-// Usage
-<FormField control={form.email} label="Email" type="email" />
-<FormField control={form.age} label="Age" type="number" />
+```tsx
+// WRONG — дублирует логику FormField, ломает schema-driven архитектуру
+<Input control={form.email} label="Email" placeholder="..." />
+<Select control={form.country} options={[...]} />
 ```
 
-### FormField for Select
+❌ **Передача компонент-пропсов через JSX вместо схемы**:
 
 ```tsx
-interface SelectFieldProps<T extends string> {
-  control: FieldNode<T>;
-  label?: string;
-  options: Array<{ value: T; label: string }>;
-}
+// WRONG — нарушает single source of truth (схема)
+<FormField control={form.email} label="Email" />
+```
+
+✅ Всё это в схеме:
+
+```ts
+{ email: { component: Input, componentProps: { label: 'Email' } } }
+```
+
+```tsx
+<FormField control={form.email} />
+```
+
+### Advanced — кастомный input через `children` slot
+
+Когда нужен низкоуровневый input, которого нет в ui-kit (маска, особый combobox):
+
+```tsx
+import { FormField } from '@reformer/ui-kit';
+import { InputMask } from 'react-input-mask';
+
+<FormField control={form.phone} testId="phone">
+  <InputMask mask="+7 (999) 999-99-99" />
+</FormField>;
+```
+
+`children` оборачивается в `CdkFormField.Control asChild` и получает все нужные
+props (`value`, `onChange`, `onBlur`, `aria-invalid`).
+
+### Advanced — write your own from scratch (rare)
+
+Если ты не хочешь подключать `@reformer/ui-kit`, пиши свои компоненты на основе
+`useFormControl` — но **сохраняй schema-driven подход**: читай label/placeholder
+из `componentProps`, не из JSX-props.
+
+```tsx
+import type { FieldNode } from '@reformer/core';
+import { useFormControl } from '@reformer/core';
 
-function SelectField<T extends string>({ control, label, options }: SelectFieldProps<T>) {
-  const { value, errors, disabled, touched } = useFormControl(control);
+type MyFormFieldProps<T> = { control: FieldNode<T> }; // ← ОДИН prop
+
+function MyFormField<T>({ control }: MyFormFieldProps<T>) {
+  const { value, errors, disabled, shouldShowError, componentProps } = useFormControl(control);
+  // componentProps = { label, placeholder, type, options, ... } — из СХЕМЫ
+  const cp = (componentProps ?? {}) as Record<string, unknown>;
 
   return (
-    <div className="form-field">
-      {label && <label>{label}</label>}
-      <select
-        value={value}
-        onChange={(e) => control.setValue(e.target.value as T)}
+    <label>
+      {cp.label && <span>{cp.label as string}</span>}
+      <input
+        type={(cp.type as string) ?? 'text'}
+        value={(value ?? '') as string}
+        placeholder={cp.placeholder as string | undefined}
         disabled={disabled}
-      >
-        {options.map((opt) => (
-          <option key={opt.value} value={opt.value}>
-            {opt.label}
-          </option>
-        ))}
-      </select>
-      {touched && errors[0] && <span className="error-message">{errors[0].message}</span>}
-    </div>
+        onChange={(e) => (control.setValue as (v: unknown) => void)(e.target.value)}
+        onBlur={() => control.markAsTouched()}
+      />
+      {shouldShowError && errors[0] && <span>{errors[0].message}</span>}
+    </label>
   );
 }
 ```
 
-### Integration with UI Libraries
+Использование — как у `FormField`:
+
+```tsx
+<MyFormField control={form.email} /> // ← без label-prop
+```
+
+### Integration with UI libraries (shadcn etc.)
+
+Если есть существующая design system — оборачивай её компоненты в один
+`MyFormField` (как выше) и используй один прop `control`. Не множь обёртки на
+тип input'а — пусть `componentProps.type` диспатчит внутри.
 
 ```tsx
-// With shadcn/ui
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
 
-function ShadcnFormField({ control, label }: FormFieldProps<string>) {
-  const { value, errors, disabled } = useFormControl(control);
+function ShadcnFormField({ control }: { control: FieldNode<string> }) {
+  const { value, errors, disabled, componentProps } = useFormControl(control);
+  const cp = (componentProps ?? {}) as Record<string, unknown>;
 
   return (
     <div className="space-y-2">
-      <Label>{label}</Label>
-      <Input value={value} onChange={(e) => control.setValue(e.target.value)} disabled={disabled} />
+      {cp.label && <Label>{cp.label as string}</Label>}
+      <Input
+        value={(value ?? '') as string}
+        onChange={(e) => control.setValue(e.target.value)}
+        disabled={disabled}
+      />
       {errors[0] && <p className="text-red-500">{errors[0].message}</p>}
     </div>
   );
@@ -3550,6 +3699,44 @@ const navRef = useRef<FormWizardHandle<MyForm>>(null);
 />
 ```
 
+### Recipe 8 — enum-typed default values (union literal widening)
+
+Когда default `value` поля — литерал union-type, TS widens его до `string`,
+ломая `FormSchema<T>` assignability:
+
+```typescript
+type Gender = 'male' | 'female';
+
+// ❌ TS error: '"male"' is not assignable to 'Gender | null'
+const schema: FormSchema<{ gender: Gender }> = {
+  gender: {
+    value: 'male', // widens to string
+    component: RadioGroup,
+    componentProps: { options: [...] },
+  },
+};
+```
+
+**Fix** — `satisfies FieldConfig<UnionType>` сужает без `as`-каста:
+
+```typescript
+gender: {
+  value: 'male',
+  component: RadioGroup,
+  componentProps: { options: [...] },
+} satisfies FieldConfig<Gender>,
+```
+
+Альтернативы:
+
+- `value: 'male' as Gender` — works, но `as`-каст. Избегай (см. anti-patterns).
+- `value: null` (если `Gender | null` допустим) — нет widening проблемы, но требует
+  null-check в render/validation.
+
+Применяется к любому union-полю: `loanType`, `employmentStatus`, `maritalStatus`,
+`propertyType`, и т.п. Симптом без этого fix'а — misleading TS2769
+"`'form' does not exist in FormSchema<...>`" (см. `05-common-mistakes.md`).
+
 ### Anti-patterns to avoid
 
 - `import { type ValidationSchemaFn } from '@reformer/core/validators'` →
@@ -3562,7 +3749,165 @@ const navRef = useRef<FormWizardHandle<MyForm>>(null);
 - `as never` cast on `computeFrom` target — never necessary; if you reach
   for it, you have one of the issues above.
 
-## 67. API Reference
+## 67. 31. ASYNC VALIDATOR WITH DEBOUNCE
+
+Для проверок типа «уникальность email», «валидация INN через API», «проверка
+адреса по DaData» используй `asyncValidators` в `FieldConfig`:
+
+```ts
+import { type FieldConfig, type FormSchema, type AsyncValidatorFn } from '@reformer/core';
+import { required, email } from '@reformer/core/validators';
+
+const checkEmailUnique: AsyncValidatorFn<string> = async (value) => {
+  if (!value) return null; // empty = valid (sync `required` separately)
+
+  try {
+    const res = await fetch(`/api/check-email?email=${encodeURIComponent(value)}`);
+    const { available } = (await res.json()) as { available: boolean };
+    return available ? null : { code: 'email-taken', message: 'Email уже зарегистрирован' };
+  } catch {
+    return { code: 'check-failed', message: 'Не удалось проверить email' };
+  }
+};
+
+const schema: FormSchema<{ email: string }> = {
+  email: {
+    value: '',
+    component: Input,
+    validators: [required(), email()], // sync first
+    asyncValidators: [checkEmailUnique], // async after sync passed
+    debounce: 500, // debounce input → API (поле `debounce`, не `asyncDebounceMs`)
+  },
+};
+```
+
+### Lifecycle
+
+1. На каждое `setValue` запускается sync `validators` (`required`, `email`)
+2. Если sync passed — стартует таймер `debounce`
+3. По истечении debounce и стабильном value — вызывается каждый `asyncValidator`
+4. Во время async-проверки `useFormControl(...).pending === true` — UI может показать спиннер
+5. Результат записывается в `errors` поля
+
+### UI integration
+
+`FormField` из `@reformer/ui-kit` автоматически рендерит `<span>Проверка...</span>`
+когда `pending === true`. Если рендеришь сам — используй:
+
+```tsx
+const { pending, errors } = useFormControl(form.email);
+return pending ? <Spinner /> : errors.length ? <Error errors={errors} /> : null;
+```
+
+### Common patterns
+
+- **Debounce 500ms** — баланс между UX и API rate-limit. Для дорогих API увеличивай
+  до 1000-2000ms.
+- **Cancellation** — если `setValue` приходит во время выполнения предыдущего async,
+  ReFormer автоматически отбрасывает результат старого вызова. Не нужно вручную
+  abort'ить fetch (но reasonable practice — поддержать `AbortSignal` через
+  `ctx.signal` если есть).
+- **Cross-field async** — для валидаций типа «дата начала > дата окончания» используй
+  sync `validators` с `applyWhen`, а не `asyncValidators`.
+
+### See also
+
+- [11-async-watchfield.md](11-async-watchfield.md) — async для `watchField`, не валидаторов
+- [29-async-preload.md](29-async-preload.md) — async preload данных в init формы
+- API: `validateAsync(field): Promise<boolean>` — manual trigger, обычно не нужен
+
+## 68. 32. ASYNC OPTIONS LOADING
+
+Для динамической подгрузки опций dropdown'а в зависимости от значения другого поля
+(например: `region` → `city options`, `carBrand` → `carModel options`) — используй
+`watchField` + `updateComponentProps({ options })`:
+
+```ts
+import { watchField } from '@reformer/core/behaviors';
+import type { BehaviorSchemaFn } from '@reformer/core';
+
+type CityOption = { value: string; label: string };
+
+async function fetchCitiesByRegion(region: string): Promise<CityOption[]> {
+  const res = await fetch(`/api/cities?region=${encodeURIComponent(region)}`);
+  return res.json();
+}
+
+const behavior: BehaviorSchemaFn<MyForm> = (path) => {
+  watchField(
+    path.registrationAddress.region,
+    async (region, ctx) => {
+      if (!region) {
+        ctx.form.registrationAddress.city.updateComponentProps({ options: [] });
+        ctx.form.registrationAddress.city.setValue('');
+        return;
+      }
+
+      // Set loading state (optional — UI показывает spinner)
+      ctx.form.registrationAddress.city.updateComponentProps({
+        loading: true,
+        options: [],
+      });
+
+      try {
+        const options = await fetchCitiesByRegion(region);
+        ctx.form.registrationAddress.city.updateComponentProps({
+          loading: false,
+          options,
+        });
+      } catch {
+        ctx.form.registrationAddress.city.updateComponentProps({
+          loading: false,
+          options: [],
+        });
+        // optionally — set error на поле через setError
+      }
+    },
+    { debounce: 300 }
+  );
+};
+```
+
+### Lifecycle
+
+1. `watchField` подписан на изменения `path.region`
+2. На каждое изменение — debounce 300ms (чтобы не fetch на каждое нажатие клавиши)
+3. После debounce — async `fetchCitiesByRegion(region)`
+4. Результат — `updateComponentProps({ options })` на target поле
+5. UI (Select / Combobox) автоматически обновится через signal на componentProps
+
+### Common patterns
+
+- **Debounce 300-500ms** — баланс между UX и rate-limit
+- **Reset target value** — при смене source очисти `setValue('')` чтобы не остался stale выбор
+- **Loading state** — `componentProps.loading: true` пока fetch идёт (UI компонент должен это поддержать)
+- **Cancellation** — ReFormer **не** отменяет старый fetch автоматически. Если предыдущий fetch ещё идёт, а пришло новое значение — новый запустится параллельно. Может приводить к race. Workaround: использовать `AbortController` через closure:
+  ```ts
+  let abortController: AbortController | null = null;
+  watchField(path.region, async (region, ctx) => {
+    abortController?.abort();
+    abortController = new AbortController();
+    try {
+      const opts = await fetchCities(region, { signal: abortController.signal });
+      ctx.form.city.updateComponentProps({ options: opts });
+    } catch (e) {
+      if ((e as Error).name === 'AbortError') return;
+      throw e;
+    }
+  });
+  ```
+
+### Initial load (preload at form mount)
+
+Для preload опций при инициализации формы — используй `async-preload` recipe (см. [29-async-preload.md](29-async-preload.md)). Не `watchField` — он не triggers на init.
+
+### See also
+
+- [11-async-watchfield.md](11-async-watchfield.md) — общий паттерн async в `watchField`
+- [29-async-preload.md](29-async-preload.md) — preload данных при инициализации
+- [31-async-validator-debounce.md](31-async-validator-debounce.md) — для async **валидации** (не options)
+
+## 69. API Reference
 
 _Auto-generated from JSDoc on public exports._
 
@@ -4640,7 +4985,7 @@ _Source: src/core/behavior/behaviors/enable-when.ts_
 
 **Signature:**
 ```typescript
-export function email<TForm, TField extends string | undefined = string>(
+export function email<TForm, TField extends string | null | undefined = string>(
   fieldPath: FieldPathNode<TForm, TField> | undefined,
   options?: ValidateOptions
 ): void
@@ -6947,7 +7292,7 @@ _Source: src/core/utils/field-path-navigator.ts_
 
 **Signature:**
 ```typescript
-export function pattern<TForm, TField extends string | undefined = string>(
+export function pattern<TForm, TField extends string | null | undefined = string>(
   fieldPath: FieldPathNode<TForm, TField> | undefined,
   regex: RegExp,
   options?: ValidateOptions
@@ -6994,7 +7339,7 @@ _Source: src/core/validation/validators/pattern.ts_
 
 **Signature:**
 ```typescript
-export function phone<TForm, TField extends string | undefined = string>(
+export function phone<TForm, TField extends string | null | undefined = string>(
   fieldPath: FieldPathNode<TForm, TField> | undefined,
   options?: ValidateOptions & {
     /** Формат телефона */
@@ -7953,7 +8298,7 @@ _Source: src/core/types/index.ts_
 
 **Signature:**
 ```typescript
-export function url<TForm, TField extends string | undefined = string>(
+export function url<TForm, TField extends string | null | undefined = string>(
   fieldPath: FieldPathNode<TForm, TField> | undefined,
   options?: ValidateOptions & {
     /** Требовать наличие протокола (http:// или https://) */

package/package.json

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