@versini/ui-hooks 5.1.0 → 5.2.0

package/dist/index.d.ts

@@ -1,246 +1,259 @@
-import * as react from 'react';
-
-/**
- * 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>
- *
- */
-declare function useClickOutside<T extends HTMLElement = any>(handler: () => void, events?: string[] | null, nodes?: (HTMLElement | null)[]): react.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.
- *
- * @example
- * ```tsx
- * const { haptic } = useHaptic();
- *
- * // Trigger a single haptic pulse
- * haptic(1);
- *
- * // Trigger two rapid haptic pulses
- * haptic(2);
- * ```
- */
-declare const useHaptic: () => {
-    haptic: (count?: number) => void;
-};
-
-interface HotkeyItemOptions {
-    preventDefault?: boolean;
-}
-type HotkeyItem$1 = [string, (event: any) => void, HotkeyItemOptions?];
-declare function getHotkeyHandler(hotkeys: HotkeyItem$1[]): (event: React.KeyboardEvent<HTMLElement> | KeyboardEvent) => void;
-
-type HotkeyItem = [
-    string,
-    (event: KeyboardEvent) => void,
-    HotkeyItemOptions?
-];
-declare function shouldFireEvent(event: KeyboardEvent, tagsToIgnore: string[], triggerOnContentEditable?: boolean): boolean;
-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
- *
- */
-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.
- */
-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
- *
- */
-declare function useIsMounted(): () => boolean;
-
-interface StorageProperties<T> {
-    /**
-     * Storage key.
-     */
-    key: string;
-    /**
-     * Default value that will be set if value is not found in storage.
-     */
-    initialValue?: T;
-}
-/**
- *
- * @example
- * import { useLocalStorage } from '@versini/ui-hooks';
- * const [value, setValue, resetValue, removeValue] = useLocalStorage({
- *   key: 'gpt-model',
- *   initialValue: 'gpt-3',
- * });
- *
- * setValue('gpt-4'); ==> "gpt-4"
- * setValue((current) => (current === 'gpt-3' ? 'gpt-4' : 'gpt-3'));
- * resetValue(); ==> "gpt-3"
- * removeValue(); ==> null
- */
-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} />;
- * });
- *
- */
-declare function useMergeRefs<T = any>(refs: Array<React.MutableRefObject<T> | React.LegacyRef<T> | undefined | null>): React.RefCallback<T>;
-
-type ObserverRect = Omit<DOMRectReadOnly, "toJSON">;
-/**
- * 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>
- */
-declare function useResizeObserver<T extends HTMLElement = any>(options?: ResizeObserverOptions): readonly [react.RefObject<T | null>, ObserverRect];
-
-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;
-}
-declare function useUncontrolled<T>({ value, defaultValue, finalValue, onChange, initialControlledDelay, }: UseUncontrolledInput<T>): [T, (value: T) => void, boolean];
-
-/**
- * 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"
- *
- */
-type UseUniqueIdOptions = string | number | {
-    id?: string | number;
-    prefix?: string;
-};
-declare function useUniqueId(options?: UseUniqueIdOptions): string | undefined;
-
-/**
- * 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();
- */
-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();
- */
-declare function useVisualViewportSize(): {
-    width: number;
-    height: number;
-};
-
-export { type HotkeyItem, type HotkeyItemOptions, type StorageProperties, type UseUniqueIdOptions, getHotkeyHandler, shouldFireEvent, useClickOutside, useHaptic, useHotkeys, useInViewport, useInterval, useIsMounted, useLocalStorage, useMergeRefs, useResizeObserver, useUncontrolled, useUniqueId, useViewportSize, useVisualViewportSize };
+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;
+
+export declare interface StorageProperties<T> {
+    /**
+     * Storage key.
+     */
+    key: string;
+    /**
+     * Default value that will be set if value is not found in storage.
+     */
+    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;
+
+/**
+ *
+ * @example
+ * import { useLocalStorage } from '@versini/ui-hooks';
+ * const [value, setValue, resetValue, removeValue] = useLocalStorage({
+ *   key: 'gpt-model',
+ *   initialValue: 'gpt-3',
+ * });
+ *
+ * setValue('gpt-4'); ==> "gpt-4"
+ * setValue((current) => (current === 'gpt-3' ? 'gpt-4' : 'gpt-3'));
+ * resetValue(); ==> "gpt-3"
+ * removeValue(); ==> null
+ */
+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 { }