indicator-ui 1.0.32 → 1.0.34

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

@@ -0,0 +1,25 @@
+import { ExtendFormPath, FormErrorsType, FormErrorType, FormPath, FormValue, UseFormServices } from '../types';
+import { Form } from '../classes';
+export declare function createFormServices<T>(deps: {
+    /** Form */
+    getForm: () => Form<T>;
+    setFormData: (data: T) => void;
+    /** 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>;
+    /** Highlight (side-effect validation) */
+    highlightField: <P extends ExtendFormPath<T>>(path: P) => Promise<boolean>;
+    highlightFields: (paths: ExtendFormPath<T>[]) => Promise<boolean>;
+    highlightFormErrors: () => Promise<boolean>;
+}): UseFormServices<T>;

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

@@ -3,3 +3,4 @@ export * from './setDataByPath';
 export * from './getFormDataPaths';
 export * from './scheme';
 export * from './fieldsProps';
+export * from './createFormServices';

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

@@ -1,2 +1,3 @@
 export * from './formTypes';
 export * from './scheme';
+export * from './services';

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

@@ -0,0 +1,51 @@
+import { ExtendFormPath, FormErrorsType, FormErrorType, FormPath, FormValue } from './formTypes';
+import { Form } from '../classes';
+export type UseFormServices<T> = {
+    /** Работа с данными формы */
+    form: {
+        /** Получить актуальные данные формы */
+        getData: () => Form<T>;
+        /** Полностью заменить данные формы */
+        setData: (data: T) => void;
+    };
+    /** Работа с полями */
+    fields: {
+        /** Получить значение поля (реактивное) */
+        get: <P extends FormPath<T>>(path: P) => FormValue<T, P> | null | undefined;
+        /** Получить значение поля (гарантированно актуальное) */
+        getSync: <P extends FormPath<T>>(path: P) => FormValue<T, P> | undefined;
+        /** Установить значение поля */
+        set: <P extends FormPath<T>>(path: P, value: FormValue<T, P> | undefined) => void;
+        /** Очистить одно или несколько полей */
+        clear: (path: FormPath<T> | FormPath<T>[]) => void;
+    };
+    /** Работа с ошибками */
+    errors: {
+        /** Получить ошибку поля */
+        get: <P extends FormPath<T>>(path: P) => FormErrorType | undefined;
+        /** Установить ошибку поля */
+        set: <P extends FormPath<T>>(path: P, error: FormErrorType) => void;
+        /** Массово установить ошибки (например, серверные) */
+        setAll: (errors: FormErrorsType<T>) => void;
+        /** Очистить все ошибки */
+        clear: () => void;
+    };
+    /** Валидация (без мутаций ошибок) */
+    validation: {
+        /** Проверить валидность поля */
+        isFieldValid: <P extends ExtendFormPath<T>>(path: P) => Promise<boolean>;
+        /** Проверить несколько полей */
+        areFieldsValid: (paths: ExtendFormPath<T>[]) => Promise<boolean>;
+        /** Проверить валидность всей формы */
+        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

@@ -1,194 +1,212 @@
 import { default as React, FormEvent } from 'react';
 import { ExtendFormPath, FieldPropsType, FormErrorsType, FormErrorType } from '..';
-import { Nullable, Undefinable } from '../../types';
-import { FormPath, FormSchemeType, FormValue } from './types';
+import { InstanceRefAttributes, Nullable, Undefinable } from '../../types';
+import { FormPath, FormSchemeType, FormValue, UseFormServices } from './types';
 type PropsType<T, Form> = [
     props?: {
         initFormData?: T;
         scheme?: FormSchemeType<T>;
-        onSubmit?: (data: Form, event: FormEvent<HTMLFormElement>) => void | Promise<void>;
+        onSubmit?: (data: Form, event: FormEvent<HTMLFormElement>, services: UseFormServices<T>) => void | Promise<void>;
         /** Callback при ошибки валидации полей */
         onSubmitError?: (event: {
             errors: FormErrorsType<T>;
-        }) => void;
+        }, services: UseFormServices<T>) => void;
+        onSubmitAttempt?: (data: T | undefined | null, event: FormEvent<HTMLFormElement>, services: UseFormServices<T>) => void;
     }
 ];
 /**
- * Хук `useForm` — универсальное решение для управления и валидации форм с полной статической типизацией.
+ * `useForm` — типобезопасный хук для управления состоянием и валидации форм.
  *
- * При указании generic-типа `Form` (например, `useForm<MyFormType>()`) вы получаете:
- * - строгую типизацию всех полей формы;
- * - контроль значений, ошибок и валидации;
- * - удобную интеграцию с готовыми компонентами (`FormField`, `FormSelectField`, `FormRadioField`, `FormSwitcherField`, `FormTextareaField`);
- * - возможность легко использовать собственные поля.
+ * Предоставляет:
+ * - централизованное управление данными формы;
+ * - декларативную регистрацию полей;
+ * - схемную и кастомную валидацию;
+ * - контролируемый submit lifecycle;
+ * - безопасный императивный API (`services`) для бизнес-логики.
  *
  * ---
- * ### 💡 Основная идея
- * Все поля формы управляются внутри хука.
- * Для внешнего контроля состояния формы и ошибок можно использовать `setFormData` и `setError`.
+ * ## 🧠 Основная идея
  *
- * При регистрации поля через `register`:
- * - создаются функции валидации;
- * - возвращаются пропсы (`FieldPropsType`), которые можно напрямую передавать в компонент поля.
+ * Хук полностью управляет состоянием формы и ошибками,
+ * а наружу отдаёт:
+ * - **декларативный API** (`register`, `registerForm`);
+ * - **императивные команды** (clear, validate, highlight);
+ * - **изолированные сервисы** для submit-логики.
  *
  * ---
- * ### ✅ Способы задания валидации
+ * ## 🔁 Submit lifecycle
  *
- * **1. Через `register`:**
- * ```tsx
- * <FormField
- *   {...register('baseInput', { required: { setting: true, message: 'Обязательное поле' } })}
- *   label="Base input"
- *   hint="Обычная строка"
- * />
- * ```
+ * Порядок вызова callbacks при submit:
  *
- * **2. Через схему `scheme`:**
- * ```ts
- * const scheme: FormSchemeType<TestFormType> = {
- *   baseInput: {
- *     minStr: { setting: 3, message: 'Минимум 3 символа' },
- *     maxStr: 10,
- *   },
- *   textarea: {
- *     custom: (value) =>
- *       value?.includes('_') ? 'В тексте есть запрещенный символ' : false,
- *     noSpace: true,
- *   },
- *   'selects.select': {
- *     required: { setting: true, message: 'Поле обязательное' },
- *   },
- * };
- * ```
+ * 1. `onSubmitAttempt` — всегда
+ * 2. Валидация формы
+ * 3. `onSubmit` — если форма валидна
+ * 4. `onSubmitError` — если есть ошибки
+ *
+ * ---
+ * ## 🔌 Callbacks
+ *
+ * Все callbacks получают объект `services` —
+ * стабильный набор команд для работы с формой
+ * (без реактивных значений и возможности вызвать submit повторно).
+ *
+ * ---
+ * ## 📥 Входные параметры
+ *
+ * | Параметр | Тип | Описание |
+ * |---------|-----|----------|
+ * | `initFormData` | `T` | Начальные данные формы |
+ * | `scheme` | `FormSchemeType<T>` | Схема валидации |
+ * | `onSubmitAttempt` | `(data, event, services) => void` | Вызывается при любой попытке submit |
+ * | `onSubmit` | `(data, event, services) => void \| Promise<void>` | Вызывается при успешной валидации |
+ * | `onSubmitError` | `({ errors }, services) => void` | Вызывается при ошибках валидации |
+ *
+ * ---
+ * ## 📤 Возвращаемое 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`
  *
- * Для более подробного ознакомления с полями схемы можно ознакомиться с типом {@link FormSchemeType}.
+ * `services` доступны **только внутри submit-callbacks**
+ * и предоставляют императивный API:
+ *
+ * - `form` — чтение и замена данных формы;
+ * - `fields` — работа с полями;
+ * - `errors` — управление ошибками;
+ * - `validation` — проверки без side-effects;
+ * - `highlight` — валидация с обновлением ошибок.
  *
  * ---
- * ### 🧩 Пример использования
+ ;
+ * @example
+ *
  * ```tsx
- * type TestFormType = {
- *   baseInput: string;
- *   textarea: string;
+ * type FormType = {
+ *   phone: string;
+ *   message: string;
  *   selects: {
- *     select: number;
- *     selectMulti: number[];
+ *     category: 'a' | 'b' | 'c';
+ *     tags: ('a' | 'b' | 'c')[];
  *   };
- *   addition: [
- *     { switcher: boolean },
- *     { radio: { multi: string[]; default: string } },
+ *   settings: [
+ *     { enabled: boolean },
+ *     { mode: { value: string } },
  *   ];
  * };
  *
- * export function FormPage() {
- *   const { register, registerForm, formData, errors, isFormValid } = useForm<TestFormType>({
+ * const scheme: FormSchemeType<FormType> = {
+ *   phone: {
+ *     required: { setting: true, message: 'Обязательное поле' },
+ *     custom: value =>
+ *       value && value.length > 5 ? false : 'Некорректный номер',
+ *   },
+ *
+ *   message: {
+ *     noSpace: true,
+ *     custom: (value, options) => {
+ *       const enabled = options.getField('settings[0].enabled');
+ *       return enabled && !value
+ *         ? 'Сообщение обязательно'
+ *         : false;
+ *     },
+ *   },
+ *
+ *   'selects.category': {
+ *     required: true,
+ *   },
+ * };
+ *
+ * export function ExampleForm() {
+ *   const {
+ *     formData,
+ *     register,
+ *     registerForm,
+ *     highlightField,
+ *     isFormValid,
+ *   } = useForm<FormType>({
  *     scheme,
- *     onSubmit: (data) => console.log('Submit data:', data),
+ *
+ *     onSubmitAttempt: (data, event, services) => {
+ *       console.log('Submit attempt:', data);
+ *     },
+ *
+ *     onSubmit: async (data, event, services) => {
+ *       // бизнес-валидация без UI-эффектов
+ *       const isValid = await services.validation.isFormValid();
+ *       if (!isValid) return;
+ *
+ *       console.log('Submit success:', data);
+ *     },
+ *
+ *     onSubmitError: ({ errors }, services) => {
+ *       // UI-валидация с подсветкой
+ *       services.highlight.form();
+ *       console.log('Submit errors:', errors);
+ *     },
  *   });
  *
  *   return (
  *     <form {...registerForm()}>
- *       <FormField
- *         {...register('baseInput', { required: { setting: true, message: 'Обязательное поле' } })}
- *         label="base input"
- *         hint="Обычная строка"
- *       />
  *
- *       <FormTextareaField {...register('textarea')} />
+ *       <input {...register('phone')} />
  *
- *       <FormSwitcherField {...register('addition[0].switcher')} />
+ *       <textarea {...register('message')} />
  *
- *       <FormRadioField {...register('addition[1].radio.default')} options={radioOptions} />
- *       <FormRadioField {...register('addition[1].radio.multi')} options={radioOptions} multiple />
+ *       <select {...register('selects.category')}>
+ *         <option value="a">A</option>
+ *         <option value="b">B</option>
+ *         <option value="c">C</option>
+ *       </select>
  *
- *       <FormSelectField
- *         {...register('selects.select')}
- *         options={selectOptions}
- *         label="selects.select"
- *         required
- *         hint="Select с выбором только одного элемента"
+ *       <input
+ *         type="checkbox"
+ *         {...register('settings[0].enabled')}
  *       />
  *
- *       <FormSelectField
- *         {...register('selects.selectMulti')}
- *         multiple
- *         required
- *         options={selectOptions}
- *         label="selects.selectMulti"
- *         hint="Select с выбором нескольких элементов"
- *       />
- *
- *       <button type="submit">Отправить</button>
- *       <button type="reset">Сбросить</button>
- *     </form>
- *   );
- * }
- * ```
+ *       <input {...register('settings[1].mode.value')} />
  *
- * ---
- * ### ⚙️ Основные методы и значения
- *
- * | Переменная / метод | Тип | Назначение |
- * |---------------------|------|-------------|
- * | `formData` | `T` | Текущее состояние формы (реактивное) |
- * | `setFormData(data)` | `(data: T) => void` | Полностью заменяет состояние формы |
- * | `getFormData()` | `() => T` | Возвращает актуальные данные формы |
- * | `errors` | `FormErrorsType<T>` | Объект всех ошибок формы |
- * | `setErrors(errors)` | `(errors: FormErrorsType<T>) => void` | Полностью заменяет состояние ошибок |
- * | `getField(path)` | `(path) => value` | Возвращает текущее значение поля (возвращает стейт) |
- * | `setField(path, value)` | `(path, value) => void` | Устанавливает значение поля |
- * | `getFieldSync(path)` | `(path) => value` | Возвращает текущее значение поля (гарантировано последнее значение) |
- * | `getError(path)` | `(path) => FormErrorType` | Возвращает ошибку конкретного поля |
- * | `setError(path, error)` | `(path, error) => void` | Устанавливает ошибку вручную |
- * | `highlightField(path)` | `(path) => Promise<boolean>` | Проверяет конкретное поле и обновляет `errors`. Возвращает результат проверки. |
- * | `highlightFields(paths)` | `(paths) => Promise<boolean>` | Проверяет несколько полей и обновляет `errors`. Возвращает результат проверки. |
- * | `highlightFormErrors()` | `() => Promise<boolean>` | Проверяет всю форму и обновляет `errors`. Возвращает результат проверки. |
- * | `isFieldValid(path)` | `(path) => Promise<boolean>` | Проверяет валидность поля (без добавления `errors`) |
- * | `areFieldsValid(paths)` | `(paths) => Promise<boolean>` | Проверяет валидность полей (без добавления `errors`) |
- * | `isFormValid()` | `() => Promise<boolean>` | Проверяет, валидна ли вся форма (без добавления `errors`) |
- * | `clearForm()` | `() => void` | Сбрасывает все значения формы |
- * | `clearErrors()` | `() => void` | Очищает все ошибки |
- * | `clearField(path | paths)` | `(path | paths) => void` | Очищает поле или поля |
- * | `register(path, config?)` | `(path, config?) => FieldPropsType` | Регистрирует поле и возвращает пропсы для компонента |
- * | `registerForm()` | `() => Pick<React.ComponentProps<'form'>, 'onSubmit' | 'onReset' | 'noValidate'>` | Возвращает обработчики и настройки для `<form>` |
- * | `getValidForm()` | `() => Promise<T | null>` | Возвращает валидную форму, в случае если форма не валидна - null |
+ *       <button type="button" onClick={() => highlightField('phone')}>
+ *         Validate phone
+ *       </button>
  *
- * ---
- * ### 🧠 `registerForm`
+ *       <button type="submit">Submit</button>
  *
- * Функция `registerForm` позволяет удобно подключить форму к системе валидации и управления состоянием,
- * не теряя контроль над поведением `onSubmit` и `onReset`.
+ *       <pre>{JSON.stringify(formData, null, 2)}</pre>
  *
- * #### Пример:
- * ```tsx
- * const { register, registerForm } = useForm<MyFormType>({
- *   onSubmit: (data) => console.log('Отправлено:', data),
- * });
- *
- * return (
- *   <form {...registerForm()}>
- *     <FormField {...register('username')} label="Имя" />
- *     <FormField {...register('email')} label="Email" />
- *     <button type="submit">Отправить</button>
- *     <button type="reset">Сбросить</button>
- *   </form>
- * );
+ *     </form>
+ *   );
+ * }
  * ```
  *
- * #### Поведение:
- * - `onSubmit`: выполняет валидацию всей формы (`isFormValid()`), при успехе вызывает переданный `onSubmit`;
- * - `onReset`: предотвращает нативный сброс, очищает значения (`clearForm()`) и ошибки (`clearErrors()`);
- * - `noValidate: true`: отключает нативную HTML5-валидацию, чтобы не мешала кастомной логике.
- *
  * ---
- * @template Form — объект, описывающий форму.
- * @template T — частичный тип формы (используется для инициализации, по умолчанию `Undefinable<Form>`).
- *
- * @param {Object} [params]
- * @param {T} [params.initFormData] — начальные данные формы.
- * @param {FormSchemeType<T>} [params.scheme] — схема валидации формы.
- * @param {(data: Form) => void | Promise<void>} [params.onSubmit] — колбэк, вызываемый при успешной отправке формы.
- *
- * @returns {object} Объект с методами и состоянием формы (см. таблицу выше).
+ * @template Form Полный тип формы
+ * @template T Тип начальных данных
  */
 export declare function useForm<Form, T extends Nullable<Undefinable<Form>> = Nullable<Undefinable<Form>>>(...args: PropsType<T, Form>): {
     formData: T | undefined;
@@ -214,7 +232,9 @@ export declare function useForm<Form, T extends Nullable<Undefinable<Form>> = Nu
         (): FieldPropsType<FormValue<T, "">>;
         <P extends FormPath<T>>(path: P, config?: FormSchemeType<T>[P]): FieldPropsType<FormValue<T, P>>;
     };
-    registerForm: () => Pick<React.ComponentProps<"form">, "onSubmit" | "onReset" | "noValidate">;
+    registerForm: () => Pick<React.ComponentProps<"form">, "onSubmit" | "onReset" | "noValidate" | "ref"> & Pick<InstanceRefAttributes<React.ComponentRef<"form">>, "instanceRef">;
     getValidForm: () => Promise<Form | null>;
+    submitForm: () => void;
+    resetForm: () => void;
 };
 export {};

package/package.json

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