@versini/ui-hooks 5.3.2 → 6.0.1

package/dist/index.d.ts

@@ -1,316 +0,0 @@
-import { RefObject } from 'react';
-
-export declare function getHotkeyHandler(hotkeys: HotkeyItem_2[]): (event: React.KeyboardEvent<HTMLElement> | KeyboardEvent) => void;
-
-export declare type HotkeyItem = [
-string,
-(event: KeyboardEvent) => void,
-HotkeyItemOptions?
-];
-
-declare type HotkeyItem_2 = [string, (event: any) => void, HotkeyItemOptions?];
-
-export declare interface HotkeyItemOptions {
-    preventDefault?: boolean;
-}
-
-declare type ObserverRect = Omit<DOMRectReadOnly, "toJSON">;
-
-export declare function shouldFireEvent(event: KeyboardEvent, tagsToIgnore: string[], triggerOnContentEditable?: boolean): boolean;
-
-/**
- * Configuration properties for the useLocalStorage hook.
- *
- * @template T - The type of the value stored in localStorage
- *
- */
-export declare interface StorageProperties<T> {
-    /**
-     * The localStorage key under which the value will be stored. Must be unique
-     * within your application to avoid conflicts.
-     */
-    key: string;
-    /**
-     * Optional default value that will be set in localStorage if no value exists.
-     * This value will be used on initial mount and when resetValue() is called.
-     */
-    initialValue?: T;
-}
-
-/**
- * Custom hooks that triggers a callback when a click is detected
- * outside the target element.
- *
- * @param handler - Function to be called when clicked outside
- * @param events - Array of events to listen to
- * @param nodes - Array of nodes to check against
- * @returns Ref to be attached to the target element
- *
- * @example
- * const ref = useClickOutside(() => {
- *  console.log('Clicked outside!');
- * });
- * <div ref={ref}>Click me!</div>
- *
- */
-export declare function useClickOutside<T extends HTMLElement = any>(handler: () => void, events?: string[] | null, nodes?: (HTMLElement | null)[]): RefObject<T | null>;
-
-/**
- * Custom hook providing imperative haptic feedback for mobile devices. Uses
- * navigator.vibrate when available, falls back to iOS switch element trick for
- * Safari on iOS devices that don't support the Vibration API.
- *
- * This hook uses a singleton pattern - only one haptic element is created in
- * the DOM regardless of how many components use this hook. The element is
- * automatically cleaned up when the last component unmounts.
- *
- * @example
- * ```tsx
- * const { haptic } = useHaptic();
- *
- * // Trigger a single haptic pulse
- * haptic(1);
- *
- * // Trigger two rapid haptic pulses
- * haptic(2);
- * ```
- *
- */
-export declare const useHaptic: () => {
-    haptic: (count?: number) => void;
-};
-
-export declare function useHotkeys(hotkeys: HotkeyItem[], tagsToIgnore?: string[], triggerOnContentEditable?: boolean): void;
-
-/**
- * Custom hook to call a function within a given interval.
- *
- * @param fn Callback function to be executed at each interval
- * @param interval  Interval time in milliseconds
- * @returns An object containing start, stop, and active state
- *
- * @example
- * const { start, stop, active } = useInterval(() => {
- *  console.log("Interval executed");
- * }, 1000);
- * start(); // To start the interval
- * stop(); // To stop the interval
- * console.log(active); // To check if the interval is active
- *
- */
-export declare function useInterval(fn: () => void, interval: number): {
-    start: () => void;
-    stop: () => void;
-    active: boolean;
-};
-
-/**
- * Hook that checks if an element is visible in the viewport.
- * @returns
- * ref: React ref object to attach to the element you want to monitor.
- * inViewport: Boolean indicating if the element is in the viewport.
- */
-export declare function useInViewport<T extends HTMLElement = any>(): {
-    ref: (node: T | null) => void;
-    inViewport: boolean;
-};
-
-/**
- * Custom hook that returns a function indicating whether the component
- * is mounted or not.
- *
- * @returns A function that returns a boolean value indicating whether
- *          the component is mounted.
- *
- * @example
- * const isMounted = useIsMounted();
- * console.log(isMounted()); // true
- *
- */
-export declare function useIsMounted(): () => boolean;
-
-/**
- * A React hook for managing state synchronized with localStorage. Uses React
- * 19's useSyncExternalStore for optimal concurrent rendering support and
- * automatic synchronization across components. Changes are automatically
- * persisted to localStorage and synchronized across all components using the
- * same key, including across browser tabs.
- *
- * Features:
- * - Automatic serialization/deserialization with JSON
- * - Type-safe with TypeScript generics
- * - Supports functional updates (similar to setState)
- * - Synchronized across components and browser tabs
- * - Handles edge cases (null, undefined, errors)
- * - Compatible with React 19+ concurrent features
- *
- * @template T - The type of the value stored in localStorage
- * @param {StorageProperties<T>} config - Configuration object with key and optional initialValue
- * @returns {[T | null, (value: T | ((current: T) => T)) => void, () => void, () => void]} A tuple containing:
- *   - [0] current value from localStorage (or null if not set)
- *   - [1] setValue function to update the stored value (supports direct value or function updater)
- *   - [2] resetValue function to restore the initialValue
- *   - [3] removeValue function to remove the value from localStorage
- *
- * @example
- * ```js
- * // Basic usage with a string value
- * import { useLocalStorage } from '@versini/ui-hooks';
- * const [model, setModel, resetModel, removeModel] = useLocalStorage({
- *   key: 'gpt-model',
- *   initialValue: 'gpt-3',
- * });
- *
- * // Direct update
- * setModel('gpt-4'); // Stores "gpt-4"
- *
- * // Functional update (receives current value)
- * setModel((current) => (current === 'gpt-3' ? 'gpt-4' : 'gpt-3'));
- *
- * // Reset to initial value
- * resetModel(); // Restores "gpt-3"
- *
- * // Remove from localStorage
- * removeModel(); // Sets value to null and removes from storage
- * ```
- *
- * @example
- * ```js
- * // Usage with complex objects
- * interface UserPreferences {
- *   theme: 'light' | 'dark';
- *   fontSize: number;
- * }
- *
- * const [prefs, setPrefs] = useLocalStorage<UserPreferences>({
- *   key: 'user-preferences',
- *   initialValue: { theme: 'light', fontSize: 14 }
- * });
- *
- * // Update specific property
- * setPrefs(current => ({ ...current, theme: 'dark' }));
- * ```
- *
- */
-export declare function useLocalStorage<T>({ key, initialValue, }: StorageProperties<T>): any[];
-
-/**
- * React utility to merge refs.
- *
- * When developing low level UI components, it is common to have to use a local
- * ref but also support an external one using React.forwardRef. Natively, React
- * does not offer a way to set two refs inside the ref property.
- *
- * @param Array of refs (object, function, etc.)
- *
- * @example
- *
- * const Example = React.forwardRef(function Example(props, ref) {
- *   const localRef = React.useRef();
- *   const mergedRefs = useMergeRefs([localRef, ref]);
- *
- *   return <div ref={mergedRefs} />;
- * });
- *
- */
-export declare function useMergeRefs<T = any>(refs: Array<React.MutableRefObject<T> | React.LegacyRef<T> | undefined | null>): React.RefCallback<T>;
-
-/**
- * A custom hook that uses the ResizeObserver API to track the size changes of a DOM element.
- *
- * @template T - The type of the DOM element being observed.
- * @param {ResizeObserverOptions} [options] - The options to configure the ResizeObserver.
- * @returns {[React.RefObject<T>, ObserverRect]} - A tuple containing the ref object and
- *                                                the observed rectangle.
- * @example
- *
- * const [rightElementRef, rect] = useResizeObserver<HTMLDivElement>();
- * <div ref={componentRef}>
- *   Observed: <code>{JSON.stringify(rect)}</code>
- * </div>
- */
-export declare function useResizeObserver<T extends HTMLElement = any>(options?: ResizeObserverOptions): readonly [RefObject<T | null>, ObserverRect];
-
-export declare function useUncontrolled<T>({ value, defaultValue, finalValue, onChange, initialControlledDelay, }: UseUncontrolledInput<T>): [T, (value: T) => void, boolean];
-
-declare interface UseUncontrolledInput<T> {
-    /** Value for controlled state */
-    value?: T;
-    /** Initial value for uncontrolled state */
-    defaultValue?: T;
-    /** Final value for uncontrolled state when value and defaultValue are not provided */
-    finalValue?: T;
-    /** Controlled state onChange handler */
-    onChange?: (value: T) => void;
-    /** Initial delay for controlled state */
-    initialControlledDelay?: number;
-}
-
-export declare function useUniqueId(options?: UseUniqueIdOptions): string | undefined;
-
-/**
- * Hook that generates a unique id that will retain its value
- * during the lifecycle of the calling functional component.
- *
- * The parameters are either
- * - nothing: a unique id will simply be generated with no prefix.
- * - a string or a number: a prefix to prepend to the generated id.
- * - an object with the following props:
- *    - id: if this is a number or a string, it will be returned as is
- *    - prefix: prefix to prepend to the generated id.
- *
- * @param {string | number | object} options
- * @returns a unique id
- *
- * @examples
- *
- * const someId = useUniqueId();
- * // -> someId = "1j3h4f5"
- *
- * const errorId = useUniqueId("av-text-input-error-");
- * // -> errorId = "av-text-input-error-1j3h4f5"
- *
- * const inputId = useUniqueId({ id: 42, prefix: "av-text-input-" });
- * // -> inputId = "av-text-input-42"
- *
- * const inputHintId = useUniqueId({
- *   prefix: "av-text-input-hint-",
- * });
- * // -> inputHintId = "av-text-input-hint-1j3h4f5"
- *
- */
-export declare type UseUniqueIdOptions = string | number | {
-    id?: string | number;
-    prefix?: string;
-};
-
-/**
- * Custom hook that returns the current viewport size. It will update
- * when the window is resized or the orientation changes.
- *
- * @returns The current viewport size
- *
- * @example
- * const { width, height } = useViewportSize();
- */
-export declare function useViewportSize(): {
-    width: number;
-    height: number;
-};
-
-/**
- * Custom hook that returns the current visual viewport size. It will update
- * when the window is resized (zoom, virtual keyboard displayed, etc.) or
- * the orientation changes.
- *
- * @returns The current visual viewport size
- *
- * @example
- * const { width, height } = useVisualViewportSize();
- */
-export declare function useVisualViewportSize(): {
-    width: number;
-    height: number;
-};
-
-export { }