altum 0.0.1

package/types/entries/hooks.d.ts

@@ -0,0 +1,329 @@
+import * as react from 'react';
+import { RefObject, PointerEvent, MouseEvent as MouseEvent$1 } from 'react';
+
+/**
+ * Опции хука `useOutsideClick`.
+ */
+interface UseOutsideClickOptions {
+    /** Подписываться только пока `true` (`true` по умолчанию) */
+    enabled?: boolean;
+}
+type OutsideClickTarget = RefObject<HTMLElement | null>;
+/**
+ * Вызывает callback при mousedown/touchstart вне одного или нескольких ref.
+ * Игнорирует клики, пока активен «suppress overlay dismiss» (см. `overlayDismiss`).
+ * Подписка снимается при `enabled: false` и при размонтировании.
+ *
+ * @param refs - Контейнер(ы), клик внутри которых не считается «снаружи».
+ * @param callback - Обработчик внешнего клика.
+ * @param options.enabled - Выключить слушатели без размонтирования.
+ *
+ * @returns Ничего — подписка на mousedown/touchstart вне ref.
+ *
+ * @example
+ * const panelRef = useRef<HTMLDivElement>(null);
+ * useOutsideClick(panelRef, () => setOpen(false), {enabled: open});
+ */
+declare function useOutsideClick(refs: OutsideClickTarget | OutsideClickTarget[], callback: (event: MouseEvent | TouchEvent) => void, options?: UseOutsideClickOptions): void;
+
+/**
+ * Публичный тип `DocumentKeyDownTarget`.
+ */
+type DocumentKeyDownTarget = 'document' | 'window';
+/**
+ * Опции хука `useDocumentKeyDown`.
+ */
+interface UseDocumentKeyDownOptions {
+    /** Слушать события только пока `true` (`true` по умолчанию) */
+    enabled?: boolean;
+    /** `document` или `window` — где вешать `keydown` (`document` по умолчанию) */
+    target?: DocumentKeyDownTarget;
+}
+/**
+ * Подписка на глобальный `keydown` с актуальным handler через ref
+ * (не нужно мемоизировать handler ради стабильности подписки).
+ *
+ * @param handler - Обработчик клавиатуры.
+ * @param options - `enabled` / `target`.
+ *
+ * @returns Ничего — подписка на глобальный keydown.
+ *
+ * @example
+ * useDocumentKeyDown((event) => {
+ *   if (event.key === 'ArrowDown') moveFocus(1);
+ * }, {enabled: isOpen});
+ */
+declare function useDocumentKeyDown(handler: (event: KeyboardEvent) => void, options?: UseDocumentKeyDownOptions): void;
+
+/**
+ * Опции хука `useEscapeKey`.
+ */
+interface UseEscapeKeyOptions {
+    enabled?: boolean;
+    target?: DocumentKeyDownTarget;
+    /**
+     * Участвовать в стеке overlay: Escape закрывает только верхний слой.
+     * @default true
+     */
+    layered?: boolean;
+}
+/**
+ * Вызывает `onEscape` на клавишу Escape (с `preventDefault`).
+ * При `layered` (дефолт) закрывается только верхний overlay в стеке.
+ *
+ * @param onEscape - Действие закрытия.
+ * @param options.enabled - Пока `false`, слушатель не активен.
+ *
+ * @example
+ * useEscapeKey(() => setOpen(false), {enabled: open});
+ */
+declare function useEscapeKey(onEscape: () => void, options?: UseEscapeKeyOptions): void;
+
+/**
+ * Блокирует scroll `document.body` со счётчиком вложений
+ * (несколько Modal / Sheet / ImageCrop одновременно).
+ * Снимает lock при `locked === false` и при размонтировании.
+ *
+ * @param locked - Активна ли блокировка для этого экземпляра.
+ *
+ * @returns Ничего — lock scroll на document.body.
+ *
+ * @example
+ * useBodyScrollLock(isOpen);
+ */
+declare function useBodyScrollLock(locked: boolean): void;
+
+/**
+ * Контролируемое / неконтролируемое состояние для компонентов с опциональными `value` + `defaultValue`.
+ *
+ * @returns `[value, setValue, isControlled]`
+ */
+declare function useControlledState<T>(controlled: T | undefined, defaultValue: T): [T, (next: T) => void, boolean];
+/**
+ * Контролируемое / неконтролируемое состояние с колбэком при изменении (onChange / onOpenChange).
+ */
+declare function useControlledStateWithCallback<T>(controlled: T | undefined, defaultValue: T, onChange?: (next: T) => void): [T, (next: T) => void, boolean];
+
+/**
+ * Опции хука `useOverlay`.
+ */
+interface UseOverlayOptions {
+    /** Overlay открыт. */
+    open: boolean;
+    /** Закрытие по Escape. @default true */
+    closeOnEscape?: boolean;
+    /** Блокировать scroll body. @default true */
+    lockScroll?: boolean;
+    /** Корень портала для inert фона. */
+    rootRef?: RefObject<HTMLElement | null>;
+    /** Возврат фокуса при закрытии. @default true */
+    restoreFocus?: boolean;
+}
+/**
+ * Композиция overlay-паттерна: scroll lock + Escape + inert + restore focus.
+ * Используется в Modal, Sheet, CommandPalette, ImageLightbox, ImageCrop.
+ */
+declare function useOverlay(onClose: () => void, { open, closeOnEscape, lockScroll, rootRef: rootRefProp, restoreFocus, }: UseOverlayOptions): void;
+
+/**
+ * Сохраняет фокус при активации (в `useLayoutEffect` — до ловушек в `useEffect`)
+ * и возвращает его только при переходе `true` → `false`.
+ * Используйте для overlay, где FocusTrap сам restore не делает.
+ *
+ * @param active - Панель открыта.
+ *
+ * @returns Ничего — сохранение и возврат фокуса.
+ *
+ * @example
+ * useFocusRestore(isOpen);
+ */
+declare function useFocusRestore(active: boolean): void;
+
+/**
+ * Помечает соседние узлы родителя `rootRef` как `inert`,
+ * пока overlay-панель открыта (фон недоступен для фокуса / AT).
+ * Снимает `inert` при деактивации / размонтировании (если атрибут ставил этот хук).
+ *
+ * @param active - Панель открыта.
+ * @param rootRef - Корень портала панели (sibling'и получают `inert`).
+ *
+ * @returns Ничего — атрибут inert на соседних узлах.
+ *
+ * @example
+ * useInertSiblings(isOpen, portalRootRef);
+ */
+declare function useInertSiblings(active: boolean, rootRef: RefObject<HTMLElement | null>): void;
+
+/**
+ * Опции хука `useOverlayPanel`.
+ */
+interface UseOverlayPanelOptions {
+    active: boolean;
+    /** Корень портала панели (sibling'и родителя получат `inert`) */
+    rootRef: RefObject<HTMLElement | null>;
+    /**
+     * Возврат фокуса при закрытии.
+     * Выключайте, если restore уже делает FocusTrap / useFocusTrap.
+     * @default true
+     */
+    restoreFocus?: boolean;
+}
+/**
+ * Единый паттерн для overlay-панелей: inert фона + опционально restore focus.
+ * Комбинирует `useInertSiblings` и `useFocusRestore`.
+ *
+ * @param options.active - Панель открыта.
+ * @param options.rootRef - Корень портала.
+ * @param options.restoreFocus - Возврат фокуса при закрытии (`true` по умолчанию).
+ *
+ * @returns Ничего — inert фона и опциональный restore focus.
+ *
+ * @example
+ * useOverlayPanel({active: isOpen, rootRef, restoreFocus: true});
+ */
+declare function useOverlayPanel({ active, rootRef, restoreFocus, }: UseOverlayPanelOptions): void;
+
+/**
+ * Опции хука `useFocusTrap`.
+ */
+interface UseFocusTrapOptions {
+    active: boolean;
+    /** Контейнер, внутри которого крутится Tab */
+    containerRef: RefObject<HTMLElement | null>;
+    /** Элемент для начального фокуса (иначе — первый focusable) */
+    initialFocusRef?: RefObject<HTMLElement | null>;
+    /** Куда вернуть фокус при деактивации (иначе — элемент до активации) */
+    returnFocusRef?: RefObject<HTMLElement | null>;
+    /**
+     * Возвращать фокус при деактивации.
+     * Выключайте, если restore делает `useOverlayPanel` / `useFocusRestore`.
+     * @default true
+     */
+    restoreFocus?: boolean;
+    /** Escape внутри ловушки */
+    onEscape?: () => void;
+}
+/**
+ * Ловушка фокуса без обёртки-компонента: Tab циклится внутри `containerRef`.
+ * Подходит для уже существующего DOM (CommandPalette, кастомные панели).
+ * Escape опционально через `onEscape`.
+ *
+ * @param options - `active`, `containerRef`, focus refs, `restoreFocus`, `onEscape`.
+ *
+ * @returns Ничего — ловушка Tab и опциональный Escape.
+ *
+ * @example
+ * useFocusTrap({
+ *   active: open,
+ *   containerRef,
+ *   initialFocusRef: inputRef,
+ *   onEscape: () => setOpen(false),
+ * });
+ */
+declare function useFocusTrap({ active, containerRef, initialFocusRef, returnFocusRef, restoreFocus, onEscape, }: UseFocusTrapOptions): void;
+
+/**
+ * Media query для «мобильной» ширины (breakpoint 768px).
+ * Используйте с `useMediaQuery(MOBILE_MEDIA_QUERY)`.
+ */
+declare const MOBILE_MEDIA_QUERY = "(max-width: 768px)";
+/**
+ * Подписка на CSS media query через `matchMedia`.
+ * На SSR / первом кадре может быть `false`, пока нет `window`.
+ *
+ * @param query - Строка media query (например `(min-width: 1024px)`).
+ * @returns `true`, если query сейчас совпадает.
+ *
+ * @example
+ * const isMobile = useMediaQuery(MOBILE_MEDIA_QUERY);
+ * if (isMobile) return <Sheet />;
+ */
+declare function useMediaQuery(query: string): boolean;
+
+interface UseLongPressOptions {
+    /** Задержка до срабатывания, мс. @default 500 */
+    delay?: number;
+    /** Не запускать long-press. */
+    disabled?: boolean;
+    /**
+     * Смещение (px), после которого жест отменяется.
+     * Слушается на `window`, чтобы срабатывать даже при nested touch/swipe.
+     * @default 10
+     */
+    moveThreshold?: number;
+}
+interface UseLongPressHandlers {
+    onPointerDown: (event: PointerEvent) => void;
+    onPointerUp: (event: PointerEvent) => void;
+    onPointerCancel: (event: PointerEvent) => void;
+    onContextMenu: (event: MouseEvent$1) => void;
+    onClick: (event: MouseEvent$1) => void;
+    /** Сбросить таймер (например, при начале горизонтального свайпа). */
+    cancel: () => void;
+}
+/**
+ * Long-press (удержание): вызывает `onLongPress` после `delay` мс.
+ * Движение отслеживается на `window` (pointer + touch), чтобы nested
+ * `touchmove` / `preventDefault` у свайпа не оставляли таймер живым.
+ * После срабатывания подавляет следующий `click` (capture + `onClick`).
+ */
+declare function useLongPress(onLongPress: () => void, options?: UseLongPressOptions): UseLongPressHandlers;
+
+/** CSS media query для `prefers-reduced-motion: reduce`. */
+declare const REDUCED_MOTION_QUERY = "(prefers-reduced-motion: reduce)";
+/**
+ * Отслеживает системную настройку «уменьшить движение».
+ * Подписывается на `matchMedia` через `useMediaQuery`.
+ *
+ * @returns `true`, если пользователь просит уменьшить анимации.
+ *
+ * @example
+ * const reduceMotion = usePrefersReducedMotion();
+ * <motion.div animate={reduceMotion ? false : {opacity: 1}} />
+ */
+declare function usePrefersReducedMotion(): boolean;
+
+/**
+ * Правила валидации поля формы для `useForm.register`.
+ * При нескольких правилах ошибка берётся по приоритету: required → pattern → validate.
+ */
+interface ValidationRules {
+    /** Текст ошибки, если значение пустое (`undefined` / `null` / `''`; `0` — не пустое) */
+    required?: string;
+    pattern?: {
+        value: RegExp;
+        message: string;
+    };
+    /**
+     * Верните строку ошибки, `true` (ок) или `false`.
+     * `false` — провал: текст `required`, иначе `'Invalid'`.
+     */
+    validate?: (val: unknown) => string | boolean;
+}
+/**
+ * Лёгкий хелпер контролируемых форм: хранит values/errors и фабрику `register`.
+ * Не делает submit — только локальный стейт и валидацию на change.
+ *
+ * @template T - Форма как объект полей (ключи → значения).
+ * @param initialValues - Начальные значения; ключи = имена полей.
+ * @returns `values`, `errors`, `register`, `hasErrors`, `setValues`.
+ *
+ * @example
+ * import {useForm} from 'altum-ui/hooks';
+ *
+ * const {values, errors, register, hasErrors} = useForm({email: ''});
+ * <TextField {...register('email', {required: 'Обязательно'})} error={errors.email} />
+ */
+declare function useForm<T extends Record<string, unknown>>(initialValues: T): {
+    values: T;
+    errors: Record<string, string>;
+    register: (name: keyof T, rules?: ValidationRules) => {
+        value: T[keyof T];
+        onChange: (val: unknown) => void;
+    };
+    hasErrors: boolean;
+    setValues: react.Dispatch<react.SetStateAction<T>>;
+};
+
+export { MOBILE_MEDIA_QUERY, REDUCED_MOTION_QUERY, useBodyScrollLock, useControlledState, useControlledStateWithCallback, useDocumentKeyDown, useEscapeKey, useFocusRestore, useFocusTrap, useForm, useInertSiblings, useLongPress, useMediaQuery, useOutsideClick, useOverlay, useOverlayPanel, usePrefersReducedMotion };
+export type { DocumentKeyDownTarget, UseDocumentKeyDownOptions, UseEscapeKeyOptions, UseFocusTrapOptions, UseLongPressHandlers, UseLongPressOptions, UseOutsideClickOptions, UseOverlayOptions, UseOverlayPanelOptions, ValidationRules };