@reformer/ui-kit 1.0.0-beta.3 → 1.0.0-beta.4

package/llms.txt

@@ -13,6 +13,7 @@
 - 06-troubleshooting.md — Troubleshooting / FAQ
 - 07-form-wizard.md — FormWizard — multi-step форма
 - 08-form-array-section.md — FormArraySection — UI для FormArray
+- 09-input-mask.md — InputMask — поля с маской ввода
 - API Reference (auto-generated from JSDoc)
 
 ## 1. Installation
@@ -1488,7 +1489,7 @@ const hasValue = Boolean(value);
 import { useRef } from 'react';
 import { FormWizard, type FormWizardStep } from '@reformer/ui-kit/form-wizard';
 import type { FormWizardHandle } from '@reformer/cdk/form-wizard';
-import type { FormProxy } from '@reformer/core';
+import type { FormProxy, ValidationSchemaFn } from '@reformer/core';
 
 // Используйте `type`, не `interface`, для structural-совместимости с
 // FormFields constraint внутри FormWizard generic'а.
@@ -1512,19 +1513,64 @@ const steps: FormWizardStep<MyForm>[] = [
   { number: 3, title: 'Готово', icon: '✓', body: <ConfirmationView /> },
 ];
 
+// ⚠️ КРИТИЧНО: `stepValidations` это **Record<number, ValidationSchemaFn<T>>**,
+// НЕ array. Если объявить как array `[step1Fn, step2Fn]` — FormWizard молча
+// пропустит валидацию, "Далее" сработает без проверок. Silent no-op, без
+// runtime warning.
+const STEP_VALIDATIONS: Record<number, ValidationSchemaFn<MyForm>> = {
+  1: (path) => {
+    required(path.email);
+    email(path.email);
+  },
+  2: (path) => {
+    required(path.password);
+    minLength(path.password, 8);
+  },
+};
+
+const fullValidation: ValidationSchemaFn<MyForm> = (path) => {
+  STEP_VALIDATIONS[1](path);
+  STEP_VALIDATIONS[2](path);
+  required(path.confirmation);
+};
+
 // ref типизируется явно типом формы; constraint `T extends Record<string, any>`
 // позволяет nullable-поля (`number | null`) внутри MyForm без TS-ошибок.
 const navRef = useRef<FormWizardHandle<MyForm>>(null);
 
+// ВАЖНО: prop-level `onSubmit` имеет signature `() => void | Promise<void>` —
+// БЕЗ аргумента values. Это by-design (см. FormWizardActionsProps в @reformer/cdk).
+// Чтобы получить values — читай их из form внутри handler:
+const handleSubmit = async () => {
+  const values = form.getValue();
+  await api.submit(values);
+};
+
 <FormWizard
   ref={navRef}
   form={form}
   config={{ stepValidations: STEP_VALIDATIONS, fullValidation }}
   steps={steps}
-  onSubmit={async (values) => api.submit(values)}
+  onSubmit={handleSubmit}
 />;
 ```
 
+### Альтернатива — imperative submit с values
+
+`navRef.current?.submit(callback)` — отдельный API, ПРИНИМАЕТ `(values: T) =>` callback.
+Удобно для save-and-exit flow:
+
+```tsx
+// FormWizardHandle.submit<R>(cb: (values: T) => Promise<R> | R): Promise<R | null>
+const handleSaveAndExit = async () => {
+  const result = await navRef.current?.submit((values) => api.saveDraft(values));
+  if (result) router.push('/dashboard');
+};
+```
+
+Различие — два разных entry point: `<FormWizard onSubmit={...}>` (no-arg, для submit-button click)
+и `navRef.current?.submit(values => ...)` (с values, для programmatic submit).
+
 ## 38. Полиморфный `step.body`
 
 `body` принимает три формы (runtime-discriminated):
@@ -1565,6 +1611,38 @@ const renderSchema = (path) => ({
 
 ui-kit FormWizard детектирует RenderNode (объект с `.component` без React-element-маркера) и оборачивает в `RenderNodeComponent` с `form={form}`.
 
+### ⚠️ RenderNode body требует RenderContextProvider
+
+Когда `step.body` это `RenderNode<T>` (renderer-react / renderer-json flow), **FormWizard ДОЛЖЕН быть обёрнут в `<RenderContextProvider>`** или находиться внутри `<FormRenderer>`. Иначе runtime-ошибка:
+
+```
+useRenderContext must be used within RenderContextProvider (FormRenderer)
+```
+
+`RenderNodeComponent` (которым FormWizard рендерит body) использует context — без провайдера контекст не найден.
+
+**Canonical mounting** для renderer-react:
+
+```tsx
+import { FormRenderer } from '@reformer/renderer-react';
+import { FormField } from '@reformer/ui-kit';
+
+// FormWizard как root render-node — FormRenderer уже даёт RenderContextProvider:
+<FormRenderer render={schema} settings={{ fieldWrapper: FormField }} />
+```
+
+**Если FormWizard рендерится напрямую** (не как root render-node, а внутри обычного React-tree, но с RenderNode bodies) — оберни вручную:
+
+```tsx
+import { RenderContextProvider } from '@reformer/renderer-react';
+
+<RenderContextProvider settings={{ fieldWrapper: FormField }}>
+  <FormWizard form={form} steps={steps} ... />
+</RenderContextProvider>
+```
+
+**TS-flow body (FC компоненты) — провайдер НЕ нужен**: ui-kit FormWizard рендерит FC напрямую без render-pipeline.
+
 ## 40. JSON
 
 ```jsonc
@@ -1766,7 +1844,120 @@ initialValue={{ type: 'apartment', description: '', estimatedValue: 0 }}
 
 FieldConfig попадает в значение поля → Textarea рендерит `[object Object]`, Checkbox флипается в `true`. Compiler/тесты не ловят.
 
-## 48. API Reference
+## 48. Schema-driven (canonical pattern)
+
+Объяви InputMask как `component` поля; передай `mask` в `componentProps`:
+
+```ts
+import { createForm, type FormSchema } from '@reformer/core';
+import { InputMask } from '@reformer/ui-kit';
+
+type ContactForm = {
+  phone: string;
+  passport: string;
+  inn: string;
+  snils: string;
+};
+
+const form = createForm<ContactForm>({
+  form: {
+    phone: {
+      value: '',
+      component: InputMask,
+      componentProps: { label: 'Телефон', mask: '+7 (999) 999-99-99' },
+    },
+    passport: {
+      value: '',
+      component: InputMask,
+      componentProps: { label: 'Серия и номер паспорта', mask: '9999 999999' },
+    },
+    inn: {
+      value: '',
+      component: InputMask,
+      componentProps: { label: 'ИНН', mask: '999999999999' },
+    },
+    snils: {
+      value: '',
+      component: InputMask,
+      componentProps: { label: 'СНИЛС', mask: '999-999-999 99' },
+    },
+  } satisfies FormSchema<ContactForm>,
+});
+```
+
+Render как обычно через `FormField`:
+
+```tsx
+import { FormField } from '@reformer/ui-kit';
+
+<FormField control={form.phone} testId="phone" />
+<FormField control={form.passport} testId="passport" />
+<FormField control={form.inn} testId="inn" />
+<FormField control={form.snils} testId="snils" />
+```
+
+## 49. Common masks
+
+| Поле                    | Маска                  | Пример вывода       |
+| ----------------------- | ---------------------- | ------------------- |
+| Телефон РФ              | `+7 (999) 999-99-99`   | `+7 (495) 123-45-67` |
+| Серия+номер паспорта    | `9999 999999`          | `4501 123456`       |
+| Серия паспорта          | `99 99`                | `45 01`             |
+| Номер паспорта          | `999999`               | `123456`            |
+| Код подразделения       | `999-999`              | `770-001`           |
+| ИНН (физлицо)           | `999999999999`         | `771234567890`      |
+| ИНН (юрлицо)            | `9999999999`           | `7712345678`        |
+| СНИЛС                   | `999-999-999 99`       | `123-456-789 01`    |
+| Почтовый индекс         | `999999`               | `123456`            |
+| Дата (DD.MM.YYYY)       | `99.99.9999`           | `15.05.1990`        |
+| Карта                   | `9999 9999 9999 9999`  | `4111 1111 1111 1111` |
+
+## 50. Validation
+
+`InputMask` пишет в значение **то, что ввёл пользователь** (с literal-символами маски).
+Для validation используй:
+
+- `required(path.phone)` — на пустоту
+- `minLength(path.phone, 18)` — для проверки длины с literal-символами (телефон ровно 18 символов)
+- `pattern(path.phone, /^\+7 \(\d{3}\) \d{3}-\d{2}-\d{2}$/)` — точный pattern если нужно
+
+```ts
+const validation: ValidationSchemaFn<ContactForm> = (path) => {
+  required(path.phone, { message: 'Телефон обязателен' });
+  pattern(path.phone, /^\+7 \(\d{3}\) \d{3}-\d{2}-\d{2}$/, {
+    message: 'Неверный формат телефона',
+  });
+
+  required(path.inn);
+  pattern(path.inn, /^\d{12}$/, { message: 'ИНН должен содержать 12 цифр' });
+};
+```
+
+## 51. Advanced — strict mask через FormField + children slot
+
+Если нужна автоматическая вставка literal-символов (true input-mask), используй
+библиотеку типа `react-input-mask` или `imask` как кастомный child в FormField:
+
+```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" maskChar="_" />
+</FormField>
+```
+
+`FormField` оборачивает child в `CdkFormField.Control asChild` и прокидывает
+`value` / `onChange` / `onBlur` / `aria-invalid`. См. рецепт
+[05-form-field-integration.md → Pattern 3](05-form-field-integration.md).
+
+## 52. See also
+
+- [02-text-fields.md](02-text-fields.md) — обычный Input
+- [05-form-field-integration.md](05-form-field-integration.md) — FormField обёртка
+- [06-troubleshooting.md](06-troubleshooting.md) — «маска не вставляется автоматически» → используй `react-input-mask`
+
+## 53. API Reference
 
 _Auto-generated from JSDoc on public exports._
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reformer/ui-kit",
-  "version": "1.0.0-beta.3",
+  "version": "1.0.0-beta.4",
   "description": "Styled form components with Tailwind CSS and Radix UI for @reformer ecosystem",
   "type": "module",
   "main": "./dist/index.js",