altum 0.0.2 → 0.0.3

package/types/entries/hooks.d.ts

@@ -1,255 +1,69 @@
 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`.
- */
+declare function useNow(intervalMs: number): Date;
+
 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 {
@@ -258,62 +72,26 @@ interface UseLongPressHandlers {
     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.
- */
+declare function usePresence(open: boolean, durationMs: number): {
+    shouldRender: boolean;
+    presented: boolean;
+};
+
 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/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>;
@@ -325,5 +103,5 @@ declare function useForm<T extends Record<string, unknown>>(initialValues: T): {
     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 { MOBILE_MEDIA_QUERY, REDUCED_MOTION_QUERY, useBodyScrollLock, useControlledState, useControlledStateWithCallback, useDocumentKeyDown, useEscapeKey, useFocusRestore, useFocusTrap, useForm, useInertSiblings, useLongPress, useMediaQuery, useNow, useOutsideClick, useOverlay, useOverlayPanel, usePrefersReducedMotion, usePresence };
 export type { DocumentKeyDownTarget, UseDocumentKeyDownOptions, UseEscapeKeyOptions, UseFocusTrapOptions, UseLongPressHandlers, UseLongPressOptions, UseOutsideClickOptions, UseOverlayOptions, UseOverlayPanelOptions, ValidationRules };