indicator-ui 1.0.33 → 1.0.35

package/dist/types/src/hooks/forms/lib/createFormServices.d.ts

@@ -1,17 +1,27 @@
 import { ExtendFormPath, FormErrorsType, FormErrorType, FormPath, FormValue, UseFormServices } from '../types';
 import { Form } from '../classes';
-export declare function createFormServices<T>(deps: {
+import { Nullable, Undefinable } from '../../../types';
+export declare function createFormServices<F, T = Nullable<Undefinable<F>>>(deps: {
+    /** Form */
     getForm: () => Form<T>;
     setFormData: (data: T) => void;
+    getValidForm: () => Promise<F | null>;
+    /** Fields */
     getField: <P extends FormPath<T>>(path: P) => FormValue<T, P> | null | undefined;
     getFieldSync: <P extends FormPath<T>>(path: P) => FormValue<T, P> | undefined;
     setField: <P extends FormPath<T>>(path: P, value: FormValue<T, P> | undefined) => void;
     clearField: (path: FormPath<T> | FormPath<T>[]) => void;
+    /** Errors */
     getError: <P extends FormPath<T>>(path: P) => FormErrorType | undefined;
     setError: <P extends FormPath<T>>(path: P, error: FormErrorType) => void;
     setErrors: (errors: FormErrorsType<T>) => void;
     clearErrors: () => void;
+    /** Validation */
     isFieldValid: <P extends ExtendFormPath<T>>(path: P) => Promise<boolean>;
     areFieldsValid: (paths: ExtendFormPath<T>[]) => Promise<boolean>;
     isFormValid: () => Promise<boolean>;
-}): UseFormServices<T>;
+    /** Highlight (side-effect validation) */
+    highlightField: <P extends ExtendFormPath<T>>(path: P) => Promise<boolean>;
+    highlightFields: (paths: ExtendFormPath<T>[]) => Promise<boolean>;
+    highlightFormErrors: () => Promise<boolean>;
+}): UseFormServices<F, T>;

package/dist/types/src/hooks/forms/types/services.d.ts

@@ -1,12 +1,14 @@
 import { ExtendFormPath, FormErrorsType, FormErrorType, FormPath, FormValue } from './formTypes';
 import { Form } from '../classes';
-export type UseFormServices<T> = {
+import { Nullable, Undefinable } from '../../../types';
+export type UseFormServices<F, T = Nullable<Undefinable<F>>> = {
     /** Работа с данными формы */
     form: {
         /** Получить актуальные данные формы */
         getData: () => Form<T>;
         /** Полностью заменить данные формы */
         setData: (data: T) => void;
+        getValidData: () => Promise<F | null>;
     };
     /** Работа с полями */
     fields: {
@@ -39,4 +41,13 @@ export type UseFormServices<T> = {
         /** Проверить валидность всей формы */
         isFormValid: () => Promise<boolean>;
     };
+    /** Подсветка ошибок (side-effect валидации) */
+    highlight: {
+        /** Подсветить ошибку конкретного поля */
+        field: <P extends ExtendFormPath<T>>(path: P) => Promise<boolean>;
+        /** Подсветить ошибки нескольких полей */
+        fields: (paths: ExtendFormPath<T>[]) => Promise<boolean>;
+        /** Подсветить все ошибки формы */
+        form: () => Promise<boolean>;
+    };
 };

package/dist/types/src/hooks/forms/useForm.d.ts

@@ -6,317 +6,207 @@ type PropsType<T, Form> = [
     props?: {
         initFormData?: T;
         scheme?: FormSchemeType<T>;
-        onSubmit?: (data: Form, event: FormEvent<HTMLFormElement>, services: UseFormServices<T>) => void | Promise<void>;
+        onSubmit?: (data: Form, event: FormEvent<HTMLFormElement>, services: UseFormServices<Form, T>) => void | Promise<void>;
         /** Callback при ошибки валидации полей */
         onSubmitError?: (event: {
             errors: FormErrorsType<T>;
-        }, services: UseFormServices<T>) => void;
+        }, services: UseFormServices<Form, T>) => void;
+        onSubmitAttempt?: (data: T | undefined | null, event: FormEvent<HTMLFormElement>, services: UseFormServices<Form, T>) => void;
     }
 ];
 /**
- * Хук `useForm` — универсальный инструмент для управления состоянием и валидации форм
- * с глубокой статической типизацией и расширяемым API.
+ * `useForm` — типобезопасный хук для управления состоянием и валидации форм.
  *
- * ---
- * ## 🧠 Ключевая идея
- *
- * `useForm` инкапсулирует:
- * - состояние формы;
- * - ошибки;
- * - правила валидации;
- * - интеграцию с `<form>` и полями.
- *
- * При этом предоставляет:
- * - декларативную работу через `register` / `registerForm`;
- * - императивные сервисы для бизнес-логики (`services`);
- * - строгую типизацию всех путей формы.
+ * Предоставляет:
+ * - централизованное управление данными формы;
+ * - декларативную регистрацию полей;
+ * - схемную и кастомную валидацию;
+ * - контролируемый submit lifecycle;
+ * - безопасный императивный API (`services`) для бизнес-логики.
  *
  * ---
- * ## 🧩 Типизация
+ * ## 🧠 Основная идея
  *
- * При указании generic-типа `Form`:
- *
- * ```ts
- * useForm<MyFormType>()
- * ```
- *
- * вы получаете:
- * - строгую типизацию `path` для всех полей;
- * - корректные типы значений и ошибок;
- * - защиту от обращения к несуществующим полям.
+ * Хук полностью управляет состоянием формы и ошибками,
+ * а наружу отдаёт:
+ * - **декларативный API** (`register`, `registerForm`);
+ * - **императивные команды** (clear, validate, highlight);
+ * - **изолированные сервисы** для submit-логики.
  *
  * ---
- * ## ✅ Валидация
- *
- * Валидация может быть задана двумя способами:
- *
- * ### 1️⃣ Через `register`
- *
- * ```tsx
- * <FormField
- *   {...register('email', {
- *     required: { setting: true, message: 'Обязательное поле' }
- *   })}
- * />
- * ```
+ * ## 🔁 Submit lifecycle
  *
- * ### 2️⃣ Через схему `scheme`
+ * Порядок вызова callbacks при submit:
  *
- * ```ts
- * const scheme: FormSchemeType<FormType> = {
- *   email: {
- *     required: true,
- *     custom: value => value.includes('@') || 'Некорректный email',
- *   },
- * };
- * ```
- *
- * Схема применяется один раз и синхронизируется с формой автоматически.
+ * 1. `onSubmitAttempt` — всегда
+ * 2. Валидация формы
+ * 3. `onSubmit` — если форма валидна
+ * 4. `onSubmitError` — если есть ошибки
  *
  * ---
- * ## 🧠 `registerForm`
+ * ## 🔌 Callbacks
  *
- * `registerForm` подключает форму к системе валидации и управления состоянием.
- *
- * ```tsx
- * <form {...registerForm()}>
- * ```
- *
- * Поведение:
- * - `onSubmit`:
- *   - предотвращает нативный submit;
- *   - проверяет валидность формы;
- *   - вызывает пользовательский `onSubmit` или `onSubmitError`;
- * - `onReset`:
- *   - предотвращает нативный reset;
- *   - очищает форму и ошибки;
- * - `noValidate: true`:
- *   - отключает HTML5-валидацию.
+ * Все callbacks получают объект `services` —
+ * стабильный набор команд для работы с формой
+ * (без реактивных значений и возможности вызвать submit повторно).
  *
  * ---
- * ## 🔌 Callbacks: `onSubmit` и `onSubmitError`
+ * ## 📥 Входные параметры
  *
- * ```ts
- * onSubmit(data, event, services)
- * onSubmitError({ errors }, services)
- * ```
+ * | Параметр | Тип | Описание |
+ * |---------|-----|----------|
+ * | `initFormData` | `T` | Начальные данные формы |
+ * | `scheme` | `FormSchemeType<T>` | Схема валидации |
+ * | `onSubmitAttempt` | `(data, event, services) => void` | Вызывается при любой попытке submit |
+ * | `onSubmit` | `(data, event, services) => void \| Promise<void>` | Вызывается при успешной валидации |
+ * | `onSubmitError` | `({ errors }, services) => void` | Вызывается при ошибках валидации |
  *
- * Помимо данных формы, колбэки получают объект `services`,
- * который предоставляет **безопасный императивный API** для бизнес-логики.
+ * ---
+ * ## 📤 Возвращаемое API
+ *
+ * | Поле | Тип | Назначение |
+ * |------|-----|------------|
+ * | `formData` | `T` | Реактивные данные формы |
+ * | `errors` | `FormErrorsType<T>` | Реактивные ошибки |
+ * | `register` | `(path, config?) => FieldProps` | Регистрация поля |
+ * | `registerForm` | `() => form props` | Подключение `<form>` |
+ * | `setFormData` | `(data) => void` | Полная замена данных формы |
+ * | `getFormData` | `() => T` | Получить актуальные данные |
+ * | `getField` | `(path) => value` | Получить значение поля |
+ * | `getFieldSync` | `(path) => value` | Получить актуальное значение поля |
+ * | `setField` | `(path, value) => void` | Установить значение поля |
+ * | `getError` | `(path) => error` | Получить ошибку поля |
+ * | `setError` | `(path, error) => void` | Установить ошибку поля |
+ * | `clearField` | `(path \| paths) => void` | Очистить поле(я) |
+ * | `clearForm` | `() => void` | Очистить форму |
+ * | `clearErrors` | `() => void` | Очистить все ошибки |
+ * | `highlightField` | `(path) => Promise<boolean>` | Валидировать поле с ошибками |
+ * | `highlightFields` | `(paths) => Promise<boolean>` | Валидировать несколько полей |
+ * | `highlightFormErrors` | `() => Promise<boolean>` | Валидировать всю форму |
+ * | `isFieldValid` | `(path) => Promise<boolean>` | Проверка поля без ошибок |
+ * | `areFieldsValid` | `(paths) => Promise<boolean>` | Проверка полей без ошибок |
+ * | `isFormValid` | `() => Promise<boolean>` | Проверка формы без ошибок |
+ * | `getValidForm` | `() => Promise<T \| null>` | Получить форму, если валидна |
+ * | `submitForm` | `() => void` | Программный submit |
+ * | `resetForm` | `() => void` | Программный reset |
  *
  * ---
  * ## 🛠 `services`
  *
- * `services` — это **стабильный объект команд**, доступный только внутри
- * `onSubmit` и `onSubmitError`.
+ * `services` доступны **только внутри submit-callbacks**
+ * и предоставляют императивный API:
  *
- * ### ✔️ Что в `services` есть:
- * - чтение и замена данных формы;
- * - работа с отдельными полями;
- * - установка и очистка ошибок;
- * - асинхронная валидация (без мутации ошибок).
- *
- * ### ❌ Чего в `services` НЕТ принципиально:
- * - реактивных значений (`formData`, `errors`);
- * - методов `submit`, `reset`, `register`;
- * - UX-логики (подсветка, фокус, скролл);
- * - возможностей повторно инициировать submit.
- *
- * Это гарантирует:
- * - отсутствие циклов;
- * - предсказуемость side-effect’ов;
- * - стабильность публичного API.
+ * - `form` — чтение и замена данных формы;
+ * - `fields` — работа с полями;
+ * - `errors` — управление ошибками;
+ * - `validation` — проверки без side-effects;
+ * - `highlight` — валидация с обновлением ошибок.
  *
  * ---
- * @template Form — полный тип формы.
- * @template T — тип начальных данных (может быть частичным).
- *
- * @param params
- * @param params.initFormData — начальные данные формы.
- * @param params.scheme — схема валидации.
- * @param params.onSubmit — вызывается при успешной валидации формы.
- * @param params.onSubmitError — вызывается при ошибках валидации.
- *
- * @returns API управления формой.
+ ;
  * @example
  *
- * ### Полноценный пример использования `useForm`
- *
- * Форма демонстрирует:
- * - вложенные структуры данных;
- * - массивы и tuple-поля;
- * - кастомную и схемную валидацию;
- * - работу с датами и диапазонами;
- * - проверку валидности формы и отдельных полей;
- * - императивные действия (очистка, валидация).
- *
- * ---
- *
  * ```tsx
- * type TestFormType = {
+ * type FormType = {
  *   phone: string;
- *   baseInput: string;
- *   textarea: string;
- *   date: string;
- *   time: string;
- *   datetime: string;
- *   dateRange: [string | undefined, string | undefined];
+ *   message: string;
  *   selects: {
- *     select: 'test1' | 'test2' | 'test3';
- *     selectMulti: ('test1' | 'test2' | 'test3')[];
+ *     category: 'a' | 'b' | 'c';
+ *     tags: ('a' | 'b' | 'c')[];
  *   };
- *   addition: [
- *     { switcher: boolean },
- *     { radio: { multi: ('test1' | 'test2' | 'test3')[]; default: string } },
+ *   settings: [
+ *     { enabled: boolean },
+ *     { mode: { value: string } },
  *   ];
- *   array: { test1: string; test2: string }[];
  * };
  *
- * const scheme: FormSchemeType<TestFormType> = {
+ * const scheme: FormSchemeType<FormType> = {
  *   phone: {
+ *     required: { setting: true, message: 'Обязательное поле' },
  *     custom: value =>
- *       value && value.length > 5 ? false : 'Ошибка',
- *   },
- *
- *   baseInput: {
- *     default: 'test string',
- *     minStr: { setting: 3, message: 'Больше 3 символов' },
- *     maxStr: 15,
+ *       value && value.length > 5 ? false : 'Некорректный номер',
  *   },
  *
- *   textarea: {
- *     default: 'test/textarea',
+ *   message: {
  *     noSpace: true,
  *     custom: (value, options) => {
- *       const radioValues = options.getField('addition[1].radio.multi');
- *       return value?.includes('_')
- *         ? 'В тексте есть запрещенный символ'
+ *       const enabled = options.getField('settings[0].enabled');
+ *       return enabled && !value
+ *         ? 'Сообщение обязательно'
  *         : false;
  *     },
  *   },
  *
- *   'selects.select': {
- *     required: { setting: true, message: 'Поле обязательное' },
- *   },
- *
- *   'array[*]': {
- *     custom: {
- *       fun: () => '',
- *     },
+ *   'selects.category': {
+ *     required: true,
  *   },
  * };
  *
- * export function FormPage() {
+ * export function ExampleForm() {
  *   const {
  *     formData,
- *     clearForm,
- *     clearErrors,
- *     highlightFormErrors,
- *     highlightField,
- *     isFormValid,
- *     isFieldValid,
  *     register,
  *     registerForm,
- *   } = useForm<TestFormType>({
+ *     highlightField,
+ *     isFormValid,
+ *   } = useForm<FormType>({
  *     scheme,
- *     onSubmit: data => {
- *       console.log('Submit data:', data);
- *     },
- *   });
  *
- *   return (
- *     <form {...registerForm()}>
+ *     onSubmitAttempt: (data, event, services) => {
+ *       console.log('Submit attempt:', data);
+ *     },
  *
- *       <FormDateRangeFieldBase {...register('dateRange')} />
+ *     onSubmit: async (data, event, services) => {
+ *       // бизнес-валидация без UI-эффектов
+ *       const isValid = await services.validation.isFormValid();
+ *       if (!isValid) return;
  *
- *       <FormDateField
- *         {...register('datetime')}
- *         inputFormat="dd.MM.yyyy HH:mm"
- *         outFormat="yyyy-MM-dd'T'HH:mmXXX"
- *         label="Дата и время"
- *       />
+ *       console.log('Submit success:', data);
+ *     },
  *
- *       <FormSelectField
- *         {...register('selects.selectMulti')}
- *         multiple
- *         options={selectOptions}
- *         label="selects.selectMulti"
- *       />
+ *     onSubmitError: ({ errors }, services) => {
+ *       // UI-валидация с подсветкой
+ *       services.highlight.form();
+ *       console.log('Submit errors:', errors);
+ *     },
+ *   });
  *
- *       <FormField
- *         {...register('phone')}
- *         label="Номер телефона"
- *         mask="+7 000 000-00-00"
- *       />
+ *   return (
+ *     <form {...registerForm()}>
  *
- *       <FormField
- *         {...register('baseInput')}
- *         label="Base input"
- *       />
+ *       <input {...register('phone')} />
  *
- *       <FormTextareaField {...register('textarea')} />
+ *       <textarea {...register('message')} />
  *
- *       <FormSwitcherField {...register('addition[0].switcher')} />
+ *       <select {...register('selects.category')}>
+ *         <option value="a">A</option>
+ *         <option value="b">B</option>
+ *         <option value="c">C</option>
+ *       </select>
  *
- *       <FormRadioField
- *         {...register('addition[1].radio.default')}
- *         options={radioOptions}
+ *       <input
+ *         type="checkbox"
+ *         {...register('settings[0].enabled')}
  *       />
  *
- *       <FormRadioField
- *         {...register('addition[1].radio.multi')}
- *         options={radioOptions}
- *         multiple
- *       />
+ *       <input {...register('settings[1].mode.value')} />
  *
- *       <FormSelectField
- *         {...register('selects.select')}
- *         options={selectOptions}
- *         required
- *       />
+ *       <button type="button" onClick={() => highlightField('phone')}>
+ *         Validate phone
+ *       </button>
  *
- *       <FormDateField
- *         {...register('date')}
- *         inputFormat="dd.MM.yyyy"
- *         outFormat="yyyy-MM-dd"
- *       />
+ *       <button type="submit">Submit</button>
  *
- *       <FormDateField
- *         {...register('time')}
- *         inputFormat="HH:mm"
- *         outFormat="HH:mmXXX"
- *       />
+ *       <pre>{JSON.stringify(formData, null, 2)}</pre>
  *
- *       <button type="submit">Отправить</button>
- *       <button type="reset">Сбросить</button>
  *     </form>
  *   );
  * }
  * ```
  *
  * ---
- *
- * ### Императивные действия
- *
- * ```ts
- * clearForm();              // очистить все значения формы
- * clearErrors();            // очистить все ошибки
- * await highlightFormErrors(); // подсветить ошибки всех полей
- * await highlightField('selects.select');
- *
- * const isValid = await isFormValid();
- * const isTextareaValid = await isFieldValid('textarea');
- * ```
- *
- * ---
- *
- * ### Просмотр текущего состояния формы
- *
- * ```tsx
- * <pre>
- *   {JSON.stringify(formData, null, 2)}
- * </pre>
- * ```
+ * @template Form Полный тип формы
+ * @template T Тип начальных данных
  */
 export declare function useForm<Form, T extends Nullable<Undefinable<Form>> = Nullable<Undefinable<Form>>>(...args: PropsType<T, Form>): {
     formData: T | undefined;

package/package.json

@@ -11,7 +11,7 @@
     "react-components",
     "ui-kit"
   ],
-  "version": "1.0.33",
+  "version": "1.0.35",
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",