@reformer/core 1.1.0-beta.8 → 2.0.0-beta.2

package/dist/hooks/types.d.ts

@@ -0,0 +1,328 @@
+import type { ValidationError } from '../core/types';
+/**
+ * Состояние поля формы, возвращаемое хуком {@link useFormControl} для {@link FieldNode}.
+ *
+ * Содержит реактивные данные поля: значение, состояние валидации, флаги взаимодействия
+ * и пользовательские props для компонентов.
+ *
+ * @typeParam T - Тип значения поля (string, number, boolean и т.д.)
+ *
+ * @example Базовое использование
+ * ```tsx
+ * interface Props {
+ *   control: FieldNode<string>;
+ * }
+ *
+ * function TextField({ control }: Props) {
+ *   const state = useFormControl(control);
+ *
+ *   return (
+ *     <div>
+ *       <input
+ *         value={state.value}
+ *         disabled={state.disabled}
+ *         onChange={e => control.setValue(e.target.value)}
+ *       />
+ *       {state.shouldShowError && state.errors[0] && (
+ *         <span className="error">{state.errors[0].message}</span>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link useFormControl} - хук для получения состояния
+ * @see {@link ArrayControlState} - состояние для массивов
+ *
+ * @group Types
+ */
+export interface FieldControlState<T> {
+    /**
+     * Текущее значение поля.
+     *
+     * @example
+     * ```tsx
+     * const { value } = useFormControl(emailField);
+     * console.log(value); // "user@example.com"
+     * ```
+     */
+    value: T;
+    /**
+     * Флаг асинхронной валидации или загрузки.
+     * `true` когда выполняется асинхронный валидатор.
+     *
+     * @example
+     * ```tsx
+     * const { pending } = useFormControl(usernameField);
+     *
+     * return (
+     *   <div>
+     *     <input {...props} />
+     *     {pending && <Spinner size="small" />}
+     *   </div>
+     * );
+     * ```
+     */
+    pending: boolean;
+    /**
+     * Флаг отключения поля.
+     * `true` когда поле недоступно для редактирования.
+     *
+     * @example
+     * ```tsx
+     * const { disabled, value } = useFormControl(field);
+     *
+     * return (
+     *   <input
+     *     value={value}
+     *     disabled={disabled}
+     *     className={disabled ? 'opacity-50' : ''}
+     *   />
+     * );
+     * ```
+     */
+    disabled: boolean;
+    /**
+     * Массив ошибок валидации.
+     * Пустой массив означает отсутствие ошибок.
+     *
+     * @example
+     * ```tsx
+     * const { errors } = useFormControl(field);
+     *
+     * return (
+     *   <ul className="error-list">
+     *     {errors.map((error, i) => (
+     *       <li key={i}>{error.message}</li>
+     *     ))}
+     *   </ul>
+     * );
+     * ```
+     */
+    errors: ValidationError[];
+    /**
+     * Флаг валидности поля.
+     * `true` когда поле прошло все валидации (errors.length === 0).
+     *
+     * @example
+     * ```tsx
+     * const { valid } = useFormControl(field);
+     *
+     * return (
+     *   <input className={valid ? 'border-green' : 'border-gray'} />
+     * );
+     * ```
+     */
+    valid: boolean;
+    /**
+     * Флаг невалидности поля.
+     * `true` когда есть ошибки валидации (errors.length > 0).
+     * Противоположность {@link valid}.
+     *
+     * @example
+     * ```tsx
+     * const { invalid } = useFormControl(field);
+     *
+     * return (
+     *   <input
+     *     aria-invalid={invalid}
+     *     className={invalid ? 'border-red' : ''}
+     *   />
+     * );
+     * ```
+     */
+    invalid: boolean;
+    /**
+     * Флаг взаимодействия с полем.
+     * `true` после того как поле потеряло фокус (blur) хотя бы один раз.
+     *
+     * @example
+     * ```tsx
+     * const { touched, invalid } = useFormControl(field);
+     *
+     * // Показываем ошибку только после взаимодействия
+     * const showError = touched && invalid;
+     * ```
+     */
+    touched: boolean;
+    /**
+     * Флаг для отображения ошибки.
+     * Комбинация touched && invalid - удобный shortcut для UI.
+     *
+     * @example
+     * ```tsx
+     * const { shouldShowError, errors } = useFormControl(field);
+     *
+     * return (
+     *   <div>
+     *     <input {...props} />
+     *     {shouldShowError && (
+     *       <span className="error">{errors[0]?.message}</span>
+     *     )}
+     *   </div>
+     * );
+     * ```
+     */
+    shouldShowError: boolean;
+    /**
+     * Пользовательские props для передачи в UI-компоненты.
+     * Устанавливаются через {@link FieldNode.setComponentProps}.
+     *
+     * @example
+     * ```tsx
+     * // Установка props
+     * field.setComponentProps({
+     *   placeholder: 'Enter email...',
+     *   maxLength: 100,
+     *   autoComplete: 'email'
+     * });
+     *
+     * // Использование в компоненте
+     * const { componentProps, value } = useFormControl(field);
+     *
+     * return (
+     *   <input
+     *     value={value}
+     *     placeholder={componentProps.placeholder}
+     *     maxLength={componentProps.maxLength}
+     *     autoComplete={componentProps.autoComplete}
+     *   />
+     * );
+     * ```
+     */
+    componentProps: Record<string, any>;
+}
+/**
+ * Состояние массива формы, возвращаемое хуком {@link useFormControl} для {@link ArrayNode}.
+ *
+ * Содержит реактивные данные массива: значения элементов, длину, состояние валидации
+ * и флаги взаимодействия.
+ *
+ * @typeParam T - Тип элемента массива (обычно объект с полями формы)
+ *
+ * @example Список с динамическим добавлением
+ * ```tsx
+ * interface Phone {
+ *   type: string;
+ *   number: string;
+ * }
+ *
+ * interface Props {
+ *   control: ArrayNode<Phone>;
+ * }
+ *
+ * function PhoneList({ control }: Props) {
+ *   const { length, valid } = useFormControl(control);
+ *
+ *   return (
+ *     <div>
+ *       {control.map((item, index) => (
+ *         <PhoneItem
+ *           key={item.id}
+ *           control={item}
+ *           onRemove={() => control.remove(index)}
+ *         />
+ *       ))}
+ *
+ *       {length === 0 && <p>No phones added</p>}
+ *
+ *       <button onClick={() => control.push({ type: 'mobile', number: '' })}>
+ *         Add Phone
+ *       </button>
+ *
+ *       {!valid && <p className="error">Please fix phone errors</p>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link useFormControl} - хук для получения состояния
+ * @see {@link FieldControlState} - состояние для полей
+ *
+ * @group Types
+ */
+export interface ArrayControlState<T> {
+    /**
+     * Массив текущих значений всех элементов.
+     *
+     * @example
+     * ```tsx
+     * const { value } = useFormControl(phonesArray);
+     * console.log(value);
+     * // [{ type: 'mobile', number: '+1234567890' }, { type: 'home', number: '+0987654321' }]
+     * ```
+     */
+    value: T[];
+    /**
+     * Количество элементов в массиве.
+     * Эквивалентно value.length, но оптимизировано для реактивности.
+     *
+     * @example
+     * ```tsx
+     * const { length } = useFormControl(itemsArray);
+     *
+     * return (
+     *   <div>
+     *     <span>Items: {length}</span>
+     *     {length >= 10 && <span>Maximum reached</span>}
+     *   </div>
+     * );
+     * ```
+     */
+    length: number;
+    /**
+     * Флаг асинхронной валидации.
+     * `true` когда выполняется асинхронный валидатор массива или любого элемента.
+     */
+    pending: boolean;
+    /**
+     * Массив ошибок валидации уровня массива.
+     * Не включает ошибки отдельных элементов.
+     *
+     * @example
+     * ```tsx
+     * // Валидатор массива
+     * validators.apply(phonesArray, {
+     *   validator: (phones) => phones.length >= 1,
+     *   message: 'At least one phone required'
+     * });
+     *
+     * // В компоненте
+     * const { errors } = useFormControl(phonesArray);
+     * // errors содержит ошибку "At least one phone required" если массив пуст
+     * ```
+     */
+    errors: ValidationError[];
+    /**
+     * Флаг валидности массива и всех его элементов.
+     * `true` только когда массив и все вложенные элементы валидны.
+     */
+    valid: boolean;
+    /**
+     * Флаг невалидности.
+     * `true` когда есть ошибки в массиве или любом элементе.
+     */
+    invalid: boolean;
+    /**
+     * Флаг взаимодействия.
+     * `true` после взаимодействия с любым элементом массива.
+     */
+    touched: boolean;
+    /**
+     * Флаг изменения.
+     * `true` когда значение массива отличается от начального.
+     *
+     * @example
+     * ```tsx
+     * const { dirty } = useFormControl(itemsArray);
+     *
+     * return (
+     *   <div>
+     *     {dirty && <span>* Unsaved changes</span>}
+     *     <button disabled={!dirty}>Save</button>
+     *   </div>
+     * );
+     * ```
+     */
+    dirty: boolean;
+}

package/dist/hooks/useFormControl.d.ts

@@ -1,48 +1,24 @@
 import type { FieldNode } from '../core/nodes/field-node';
 import type { ArrayNode } from '../core/nodes/array-node';
-import type { FormValue, ValidationError, FormFields } from '../core/types';
+import type { FormValue, FormFields } from '../core/types';
+import type { FieldControlState, ArrayControlState } from './types';
 /**
- * @internal
- */
-interface FieldControlState<T> {
-    value: T;
-    pending: boolean;
-    disabled: boolean;
-    errors: ValidationError[];
-    valid: boolean;
-    invalid: boolean;
-    touched: boolean;
-    shouldShowError: boolean;
-    componentProps: Record<string, any>;
-}
-/**
- * @internal
- */
-interface ArrayControlState<T> {
-    value: T[];
-    length: number;
-    pending: boolean;
-    errors: ValidationError[];
-    valid: boolean;
-    invalid: boolean;
-    touched: boolean;
-    dirty: boolean;
-}
-/**
- * Хук для получения только значения поля без подписки на errors, valid и т.д.
- * Используйте когда нужно только значение для условного рендеринга.
+ * React-хук для подписки на состояние {@link ArrayNode}.
+ *
+ * @typeParam T - Тип элемента массива
+ * @param control - ArrayNode или undefined
+ * @returns Состояние массива {@link ArrayControlState}
  *
- * @group React Hooks
- */
-export declare function useFormControlValue<T extends FormValue>(control: FieldNode<T>): T;
-/**
- * Хук для работы с ArrayNode - возвращает состояние массива с подписками на сигналы
  * @group React Hooks
  */
 export declare function useFormControl<T extends FormFields>(control: ArrayNode<T> | undefined): ArrayControlState<T>;
 /**
- * Хук для работы с FieldNode - возвращает состояние поля с подписками на сигналы
+ * React-хук для подписки на состояние {@link FieldNode}.
+ *
+ * @typeParam T - Тип значения поля
+ * @param control - FieldNode для подписки
+ * @returns Состояние поля {@link FieldControlState}
+ *
  * @group React Hooks
  */
 export declare function useFormControl<T extends FormValue>(control: FieldNode<T>): FieldControlState<T>;
-export {};

package/dist/hooks/useFormControlValue.d.ts

@@ -0,0 +1,167 @@
+import type { FieldNode } from '../core/nodes/field-node';
+import type { FormValue } from '../core/types';
+/**
+ * React-хук для подписки только на значение поля.
+ *
+ * Оптимизированная версия {@link useFormControl}, которая подписывается
+ * только на сигнал `value`. Компонент не будет ре-рендериться при изменении
+ * `errors`, `touched`, `valid` и других свойств состояния.
+ *
+ * ## Когда использовать
+ *
+ * - **Условный рендеринг** на основе значения другого поля
+ * - **Вычисляемые значения** зависящие от значения поля
+ * - **Read-only отображение** значения без интерактивности
+ * - **Оптимизация производительности** когда не нужны другие свойства состояния
+ *
+ * ## Когда НЕ использовать
+ *
+ * Если компоненту нужны `errors`, `touched`, `disabled` или другие свойства -
+ * используйте {@link useFormControl}. Множественные подписки на один контрол
+ * через разные хуки менее эффективны, чем одна подписка через `useFormControl`.
+ *
+ * @typeParam T - Тип значения поля
+ * @param control - FieldNode для подписки на значение
+ * @returns Текущее значение поля
+ *
+ * @example Условный рендеринг секции
+ * ```tsx
+ * import { useFormControlValue } from '@reformer/core';
+ *
+ * interface FormFields {
+ *   hasShipping: FieldNode<boolean>;
+ *   shippingAddress: GroupNode<AddressFields>;
+ * }
+ *
+ * function ShippingSection({ form }: { form: FormFields }) {
+ *   // Подписка только на значение checkbox
+ *   const hasShipping = useFormControlValue(form.hasShipping);
+ *
+ *   if (!hasShipping) {
+ *     return null;
+ *   }
+ *
+ *   return (
+ *     <div className="shipping-section">
+ *       <h3>Shipping Address</h3>
+ *       <AddressForm control={form.shippingAddress} />
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Динамические опции на основе другого поля
+ * ```tsx
+ * interface FormFields {
+ *   country: FieldNode<string>;
+ *   city: FieldNode<string>;
+ * }
+ *
+ * function CitySelect({ form }: { form: FormFields }) {
+ *   const country = useFormControlValue(form.country);
+ *   const { value, disabled } = useFormControl(form.city);
+ *
+ *   // Получаем города для выбранной страны
+ *   const cities = useMemo(() => getCitiesForCountry(country), [country]);
+ *
+ *   // Сбрасываем город при смене страны
+ *   useEffect(() => {
+ *     form.city.setValue('');
+ *   }, [country, form.city]);
+ *
+ *   return (
+ *     <select
+ *       value={value}
+ *       disabled={disabled || !country}
+ *       onChange={e => form.city.setValue(e.target.value)}
+ *     >
+ *       <option value="">Select city...</option>
+ *       {cities.map(city => (
+ *         <option key={city.id} value={city.id}>{city.name}</option>
+ *       ))}
+ *     </select>
+ *   );
+ * }
+ * ```
+ *
+ * @example Отображение суммы в реальном времени
+ * ```tsx
+ * interface OrderItem {
+ *   quantity: FieldNode<number>;
+ *   price: FieldNode<number>;
+ * }
+ *
+ * function OrderTotal({ items }: { items: ArrayNode<OrderItem> }) {
+ *   // Для каждого элемента получаем только значения
+ *   const quantities = items.map(item => useFormControlValue(item.controls.quantity));
+ *   const prices = items.map(item => useFormControlValue(item.controls.price));
+ *
+ *   const total = quantities.reduce((sum, qty, i) => sum + qty * prices[i], 0);
+ *
+ *   return (
+ *     <div className="order-total">
+ *       <strong>Total: ${total.toFixed(2)}</strong>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Preview значения
+ * ```tsx
+ * interface MarkdownEditorProps {
+ *   control: FieldNode<string>;
+ * }
+ *
+ * function MarkdownPreview({ control }: MarkdownEditorProps) {
+ *   // Подписка только на значение для preview
+ *   const markdown = useFormControlValue(control);
+ *
+ *   const html = useMemo(() => marked(markdown), [markdown]);
+ *
+ *   return (
+ *     <div
+ *       className="markdown-preview"
+ *       dangerouslySetInnerHTML={{ __html: html }}
+ *     />
+ *   );
+ * }
+ *
+ * // Основной редактор использует useFormControl для полного состояния
+ * function MarkdownEditor({ control }: MarkdownEditorProps) {
+ *   const { value, shouldShowError, errors } = useFormControl(control);
+ *
+ *   return (
+ *     <div className="editor-container">
+ *       <textarea
+ *         value={value}
+ *         onChange={e => control.setValue(e.target.value)}
+ *       />
+ *       {shouldShowError && <span className="error">{errors[0]?.message}</span>}
+ *
+ *       {/* Preview обновляется только при изменении value *}
+ *       <MarkdownPreview control={control} />
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Счётчик символов
+ * ```tsx
+ * function CharacterCounter({ control, max }: { control: FieldNode<string>; max: number }) {
+ *   const value = useFormControlValue(control);
+ *   const remaining = max - value.length;
+ *
+ *   return (
+ *     <span className={remaining < 20 ? 'warning' : ''}>
+ *       {remaining} characters remaining
+ *     </span>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link useFormControl} - для полного состояния поля
+ * @see {@link FieldNode} - тип контрола поля
+ *
+ * @group React Hooks
+ */
+export declare function useFormControlValue<T extends FormValue>(control: FieldNode<T>): T;

package/dist/hooks/useSignalSubscription.d.ts

@@ -0,0 +1,17 @@
+import { type Signal } from '@preact/signals-core';
+/** @internal */
+export type SignalMap = Record<string, Signal<unknown>>;
+/** @internal */
+export type ExtractSignalValues<T extends SignalMap> = {
+    [K in keyof T]: T[K] extends Signal<infer V> ? V : never;
+};
+/** @internal */
+export interface SignalConfig<K extends string> {
+    key: K;
+    useShallowArrayEqual?: boolean;
+}
+/**
+ * Хук для подписки на набор сигналов с кешированием
+ * @internal
+ */
+export declare function useSignalSubscription<TSignals extends SignalMap, TSnapshot extends ExtractSignalValues<TSignals>>(signals: TSignals, configs: SignalConfig<Extract<keyof TSignals, string>>[], buildSnapshot: (values: ExtractSignalValues<TSignals>) => TSnapshot): TSnapshot;

package/dist/index.d.ts

@@ -6,7 +6,9 @@ export { FieldNode } from './core/nodes/field-node';
 export { GroupNode } from './core/nodes/group-node';
 export { ArrayNode } from './core/nodes/array-node';
 export type { SetValueOptions } from './core/nodes/form-node';
-export { useFormControl, useFormControlValue } from './hooks/useFormControl';
+export { useFormControl } from './hooks/useFormControl';
+export { useFormControlValue } from './hooks/useFormControlValue';
+export type { FieldControlState, ArrayControlState } from './hooks/types';
 export type { BehaviorSchemaFn } from './core/behavior/types';
 export { validateForm } from './core/validation/validate-form';
 export * as behaviors from './core/behavior';