indicator-ui 1.0.31 → 1.0.33

package/dist/styles/colors/css-variables/secondary-var.css

@@ -71,4 +71,19 @@
     --teal-800: #125D56;
     --teal-900: #134E48;
     --teal-950: #0A2926;
+}
+
+:root {
+    --rose-25: #FFF5F6;
+    --rose-50: #FFF1F3;
+    --rose-100: #FFE4E8;
+    --rose-200: #FECDD6;
+    --rose-300: #FEA3B4;
+    --rose-400: #FD6F8E;
+    --rose-500: #F63D68;
+    --rose-600: #E31B54;
+    --rose-700: #C01048;
+    --rose-800: #A11043;
+    --rose-900: #89123E;
+    --rose-950: #510B24;
 }

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

@@ -0,0 +1,17 @@
+import { ExtendFormPath, FormErrorsType, FormErrorType, FormPath, FormValue, UseFormServices } from '../types';
+import { Form } from '../classes';
+export declare function createFormServices<T>(deps: {
+    getForm: () => Form<T>;
+    setFormData: (data: T) => void;
+    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;
+    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;
+    isFieldValid: <P extends ExtendFormPath<T>>(path: P) => Promise<boolean>;
+    areFieldsValid: (paths: ExtendFormPath<T>[]) => Promise<boolean>;
+    isFormValid: () => 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,42 @@
+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>;
+    };
+};

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

@@ -1,120 +1,290 @@
 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;
     }
 ];
 /**
- * Хук `useForm` — универсальное решение для управления и валидации форм с полной статической типизацией.
+ * Хук `useForm` — универсальный инструмент для управления состоянием и валидации форм
+ * с глубокой статической типизацией и расширяемым API.
  *
- * При указании generic-типа `Form` (например, `useForm<MyFormType>()`) вы получаете:
- * - строгую типизацию всех полей формы;
- * - контроль значений, ошибок и валидации;
- * - удобную интеграцию с готовыми компонентами (`FormField`, `FormSelectField`, `FormRadioField`, `FormSwitcherField`, `FormTextareaField`);
- * - возможность легко использовать собственные поля.
+ * ---
+ * ## 🧠 Ключевая идея
+ *
+ * `useForm` инкапсулирует:
+ * - состояние формы;
+ * - ошибки;
+ * - правила валидации;
+ * - интеграцию с `<form>` и полями.
+ *
+ * При этом предоставляет:
+ * - декларативную работу через `register` / `registerForm`;
+ * - императивные сервисы для бизнес-логики (`services`);
+ * - строгую типизацию всех путей формы.
  *
  * ---
- * ### 💡 Основная идея
- * Все поля формы управляются внутри хука.
- * Для внешнего контроля состояния формы и ошибок можно использовать `setFormData` и `setError`.
+ * ## 🧩 Типизация
+ *
+ * При указании generic-типа `Form`:
+ *
+ * ```ts
+ * useForm<MyFormType>()
+ * ```
  *
- * При регистрации поля через `register`:
- * - создаются функции валидации;
- * - возвращаются пропсы (`FieldPropsType`), которые можно напрямую передавать в компонент поля.
+ * вы получаете:
+ * - строгую типизацию `path` для всех полей;
+ * - корректные типы значений и ошибок;
+ * - защиту от обращения к несуществующим полям.
  *
  * ---
- * ### ✅ Способы задания валидации
+ * ## ✅ Валидация
+ *
+ * Валидация может быть задана двумя способами:
+ *
+ * ### 1️⃣ Через `register`
  *
- * **1. Через `register`:**
  * ```tsx
  * <FormField
- *   {...register('baseInput', { required: { setting: true, message: 'Обязательное поле' } })}
- *   label="Base input"
- *   hint="Обычная строка"
+ *   {...register('email', {
+ *     required: { setting: true, message: 'Обязательное поле' }
+ *   })}
  * />
  * ```
  *
- * **2. Через схему `scheme`:**
+ * ### 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: 'Поле обязательное' },
+ * const scheme: FormSchemeType<FormType> = {
+ *   email: {
+ *     required: true,
+ *     custom: value => value.includes('@') || 'Некорректный email',
  *   },
  * };
  * ```
  *
- * Для более подробного ознакомления с полями схемы можно ознакомиться с типом {@link FormSchemeType}.
+ * Схема применяется один раз и синхронизируется с формой автоматически.
  *
  * ---
- * ### 🧩 Пример использования
+ * ## 🧠 `registerForm`
+ *
+ * `registerForm` подключает форму к системе валидации и управления состоянием.
+ *
+ * ```tsx
+ * <form {...registerForm()}>
+ * ```
+ *
+ * Поведение:
+ * - `onSubmit`:
+ *   - предотвращает нативный submit;
+ *   - проверяет валидность формы;
+ *   - вызывает пользовательский `onSubmit` или `onSubmitError`;
+ * - `onReset`:
+ *   - предотвращает нативный reset;
+ *   - очищает форму и ошибки;
+ * - `noValidate: true`:
+ *   - отключает HTML5-валидацию.
+ *
+ * ---
+ * ## 🔌 Callbacks: `onSubmit` и `onSubmitError`
+ *
+ * ```ts
+ * onSubmit(data, event, services)
+ * onSubmitError({ errors }, services)
+ * ```
+ *
+ * Помимо данных формы, колбэки получают объект `services`,
+ * который предоставляет **безопасный императивный API** для бизнес-логики.
+ *
+ * ---
+ * ## 🛠 `services`
+ *
+ * `services` — это **стабильный объект команд**, доступный только внутри
+ * `onSubmit` и `onSubmitError`.
+ *
+ * ### ✔️ Что в `services` есть:
+ * - чтение и замена данных формы;
+ * - работа с отдельными полями;
+ * - установка и очистка ошибок;
+ * - асинхронная валидация (без мутации ошибок).
+ *
+ * ### ❌ Чего в `services` НЕТ принципиально:
+ * - реактивных значений (`formData`, `errors`);
+ * - методов `submit`, `reset`, `register`;
+ * - UX-логики (подсветка, фокус, скролл);
+ * - возможностей повторно инициировать submit.
+ *
+ * Это гарантирует:
+ * - отсутствие циклов;
+ * - предсказуемость side-effect’ов;
+ * - стабильность публичного API.
+ *
+ * ---
+ * @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 = {
+ *   phone: string;
  *   baseInput: string;
  *   textarea: string;
+ *   date: string;
+ *   time: string;
+ *   datetime: string;
+ *   dateRange: [string | undefined, string | undefined];
  *   selects: {
- *     select: number;
- *     selectMulti: number[];
+ *     select: 'test1' | 'test2' | 'test3';
+ *     selectMulti: ('test1' | 'test2' | 'test3')[];
  *   };
  *   addition: [
  *     { switcher: boolean },
- *     { radio: { multi: string[]; default: string } },
+ *     { radio: { multi: ('test1' | 'test2' | 'test3')[]; default: string } },
  *   ];
+ *   array: { test1: string; test2: string }[];
+ * };
+ *
+ * const scheme: FormSchemeType<TestFormType> = {
+ *   phone: {
+ *     custom: value =>
+ *       value && value.length > 5 ? false : 'Ошибка',
+ *   },
+ *
+ *   baseInput: {
+ *     default: 'test string',
+ *     minStr: { setting: 3, message: 'Больше 3 символов' },
+ *     maxStr: 15,
+ *   },
+ *
+ *   textarea: {
+ *     default: 'test/textarea',
+ *     noSpace: true,
+ *     custom: (value, options) => {
+ *       const radioValues = options.getField('addition[1].radio.multi');
+ *       return value?.includes('_')
+ *         ? 'В тексте есть запрещенный символ'
+ *         : false;
+ *     },
+ *   },
+ *
+ *   'selects.select': {
+ *     required: { setting: true, message: 'Поле обязательное' },
+ *   },
+ *
+ *   'array[*]': {
+ *     custom: {
+ *       fun: () => '',
+ *     },
+ *   },
  * };
  *
  * export function FormPage() {
- *   const { register, registerForm, formData, errors, isFormValid } = useForm<TestFormType>({
+ *   const {
+ *     formData,
+ *     clearForm,
+ *     clearErrors,
+ *     highlightFormErrors,
+ *     highlightField,
+ *     isFormValid,
+ *     isFieldValid,
+ *     register,
+ *     registerForm,
+ *   } = useForm<TestFormType>({
  *     scheme,
- *     onSubmit: (data) => console.log('Submit data:', data),
+ *     onSubmit: data => {
+ *       console.log('Submit data:', data);
+ *     },
  *   });
  *
  *   return (
  *     <form {...registerForm()}>
+ *
+ *       <FormDateRangeFieldBase {...register('dateRange')} />
+ *
+ *       <FormDateField
+ *         {...register('datetime')}
+ *         inputFormat="dd.MM.yyyy HH:mm"
+ *         outFormat="yyyy-MM-dd'T'HH:mmXXX"
+ *         label="Дата и время"
+ *       />
+ *
+ *       <FormSelectField
+ *         {...register('selects.selectMulti')}
+ *         multiple
+ *         options={selectOptions}
+ *         label="selects.selectMulti"
+ *       />
+ *
+ *       <FormField
+ *         {...register('phone')}
+ *         label="Номер телефона"
+ *         mask="+7 000 000-00-00"
+ *       />
+ *
  *       <FormField
- *         {...register('baseInput', { required: { setting: true, message: 'Обязательное поле' } })}
- *         label="base input"
- *         hint="Обычная строка"
+ *         {...register('baseInput')}
+ *         label="Base input"
  *       />
  *
  *       <FormTextareaField {...register('textarea')} />
  *
  *       <FormSwitcherField {...register('addition[0].switcher')} />
  *
- *       <FormRadioField {...register('addition[1].radio.default')} options={radioOptions} />
- *       <FormRadioField {...register('addition[1].radio.multi')} options={radioOptions} multiple />
+ *       <FormRadioField
+ *         {...register('addition[1].radio.default')}
+ *         options={radioOptions}
+ *       />
+ *
+ *       <FormRadioField
+ *         {...register('addition[1].radio.multi')}
+ *         options={radioOptions}
+ *         multiple
+ *       />
  *
  *       <FormSelectField
  *         {...register('selects.select')}
  *         options={selectOptions}
- *         label="selects.select"
  *         required
- *         hint="Select с выбором только одного элемента"
  *       />
  *
- *       <FormSelectField
- *         {...register('selects.selectMulti')}
- *         multiple
- *         required
- *         options={selectOptions}
- *         label="selects.selectMulti"
- *         hint="Select с выбором нескольких элементов"
+ *       <FormDateField
+ *         {...register('date')}
+ *         inputFormat="dd.MM.yyyy"
+ *         outFormat="yyyy-MM-dd"
+ *       />
+ *
+ *       <FormDateField
+ *         {...register('time')}
+ *         inputFormat="HH:mm"
+ *         outFormat="HH:mmXXX"
  *       />
  *
  *       <button type="submit">Отправить</button>
@@ -125,70 +295,28 @@ type PropsType<T, Form> = [
  * ```
  *
  * ---
- * ### ⚙️ Основные методы и значения
- *
- * | Переменная / метод | Тип | Назначение |
- * |---------------------|------|-------------|
- * | `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 |
  *
- * ---
- * ### 🧠 `registerForm`
+ * ### Императивные действия
  *
- * Функция `registerForm` позволяет удобно подключить форму к системе валидации и управления состоянием,
- * не теряя контроль над поведением `onSubmit` и `onReset`.
+ * ```ts
+ * clearForm();              // очистить все значения формы
+ * clearErrors();            // очистить все ошибки
+ * await highlightFormErrors(); // подсветить ошибки всех полей
+ * await highlightField('selects.select');
  *
- * #### Пример:
- * ```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>
- * );
+ * const isValid = await isFormValid();
+ * const isTextareaValid = await isFieldValid('textarea');
  * ```
  *
- * #### Поведение:
- * - `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} Объект с методами и состоянием формы (см. таблицу выше).
+ * ```tsx
+ * <pre>
+ *   {JSON.stringify(formData, null, 2)}
+ * </pre>
+ * ```
  */
 export declare function useForm<Form, T extends Nullable<Undefinable<Form>> = Nullable<Undefinable<Form>>>(...args: PropsType<T, Form>): {
     formData: T | undefined;
@@ -214,7 +342,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.31",
+  "version": "1.0.33",
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",