npm - @alessiofrittoli/react-hooks - Versions diffs - 1.2.0 → 2.0.1 - Mend

@alessiofrittoli/react-hooks 1.2.0 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (96) hide show

package/README.md +387 -73
package/dist/eslint.js +1 -1
package/dist/eslint.mjs +1 -1
package/dist/index.d.mts +940 -11
package/dist/index.d.ts +940 -11
package/dist/index.js +1 -1
package/dist/index.mjs +1 -1
package/package.json +26 -34
package/dist/browser-api/index.d.mts +0 -6
package/dist/browser-api/index.d.ts +0 -6
package/dist/browser-api/index.js +0 -1
package/dist/browser-api/index.mjs +0 -1
package/dist/browser-api/storage/index.d.mts +0 -4
package/dist/browser-api/storage/index.d.ts +0 -4
package/dist/browser-api/storage/index.js +0 -1
package/dist/browser-api/storage/index.mjs +0 -1
package/dist/browser-api/storage/useLocalStorage.d.mts +0 -11
package/dist/browser-api/storage/useLocalStorage.d.ts +0 -11
package/dist/browser-api/storage/useLocalStorage.js +0 -1
package/dist/browser-api/storage/useLocalStorage.mjs +0 -1
package/dist/browser-api/storage/useSessionStorage.d.mts +0 -11
package/dist/browser-api/storage/useSessionStorage.d.ts +0 -11
package/dist/browser-api/storage/useSessionStorage.js +0 -1
package/dist/browser-api/storage/useSessionStorage.mjs +0 -1
package/dist/browser-api/storage/useStorage.d.mts +0 -12
package/dist/browser-api/storage/useStorage.d.ts +0 -12
package/dist/browser-api/storage/useStorage.js +0 -1
package/dist/browser-api/storage/useStorage.mjs +0 -1
package/dist/browser-api/useIsPortrait.d.mts +0 -10
package/dist/browser-api/useIsPortrait.d.ts +0 -10
package/dist/browser-api/useIsPortrait.js +0 -1
package/dist/browser-api/useIsPortrait.mjs +0 -1
package/dist/browser-api/useMediaQuery.d.mts +0 -11
package/dist/browser-api/useMediaQuery.d.ts +0 -11
package/dist/browser-api/useMediaQuery.js +0 -1
package/dist/browser-api/useMediaQuery.mjs +0 -1
package/dist/chunk-26XSIIUK.mjs +0 -1
package/dist/chunk-2CZNCZFR.mjs +0 -0
package/dist/chunk-43RVMR6S.mjs +0 -1
package/dist/chunk-4BGMCO3F.js +0 -1
package/dist/chunk-65SF33P4.mjs +0 -1
package/dist/chunk-6BSD56XC.js +0 -1
package/dist/chunk-6IRIG5HU.mjs +0 -1
package/dist/chunk-7ILYMOVB.js +0 -1
package/dist/chunk-AJKPRTOJ.mjs +0 -1
package/dist/chunk-EFFJB2GR.js +0 -1
package/dist/chunk-FUCUVFLW.js +0 -1
package/dist/chunk-G55NP3QG.js +0 -1
package/dist/chunk-HO57SPST.js +0 -1
package/dist/chunk-HZLWSH3W.mjs +0 -1
package/dist/chunk-IDNLFWFO.js +0 -1
package/dist/chunk-RENUP2VU.mjs +0 -1
package/dist/chunk-SNMJ53QB.js +0 -1
package/dist/chunk-SW7BCMZF.js +0 -1
package/dist/chunk-TA6PCHH4.js +0 -1
package/dist/chunk-UAJXVBNR.mjs +0 -1
package/dist/chunk-UXNKH2MC.mjs +0 -1
package/dist/chunk-VLSP3MAN.js +0 -1
package/dist/chunk-WLIFJNZA.mjs +0 -0
package/dist/chunk-WOVEE75M.js +0 -1
package/dist/chunk-YAZXPL6I.mjs +0 -1
package/dist/chunk-YLUTFORB.js +0 -1
package/dist/chunk-YQO25XKN.mjs +0 -0
package/dist/chunk-ZNAB4TYW.mjs +0 -0
package/dist/dom-api/index.d.mts +0 -2
package/dist/dom-api/index.d.ts +0 -2
package/dist/dom-api/index.js +0 -1
package/dist/dom-api/index.mjs +0 -1
package/dist/dom-api/useFocusTrap.d.mts +0 -15
package/dist/dom-api/useFocusTrap.d.ts +0 -15
package/dist/dom-api/useFocusTrap.js +0 -1
package/dist/dom-api/useFocusTrap.mjs +0 -1
package/dist/dom-api/useScrollBlock.d.mts +0 -8
package/dist/dom-api/useScrollBlock.d.ts +0 -8
package/dist/dom-api/useScrollBlock.js +0 -1
package/dist/dom-api/useScrollBlock.mjs +0 -1
package/dist/misc/index.d.mts +0 -3
package/dist/misc/index.d.ts +0 -3
package/dist/misc/index.js +0 -1
package/dist/misc/index.mjs +0 -1
package/dist/misc/useIsClient.d.mts +0 -8
package/dist/misc/useIsClient.d.ts +0 -8
package/dist/misc/useIsClient.js +0 -1
package/dist/misc/useIsClient.mjs +0 -1
package/dist/misc/useIsFirstRender.d.mts +0 -9
package/dist/misc/useIsFirstRender.d.ts +0 -9
package/dist/misc/useIsFirstRender.js +0 -1
package/dist/misc/useIsFirstRender.mjs +0 -1
package/dist/misc/usePagination.d.mts +0 -12
package/dist/misc/usePagination.d.ts +0 -12
package/dist/misc/usePagination.js +0 -1
package/dist/misc/usePagination.mjs +0 -1
package/dist/misc/useUpdateEffect.d.mts +0 -9
package/dist/misc/useUpdateEffect.d.ts +0 -9
package/dist/misc/useUpdateEffect.js +0 -1
package/dist/misc/useUpdateEffect.mjs +0 -1

package/dist/index.d.mts CHANGED Viewed

@@ -1,11 +1,940 @@
-export { useStorage } from './browser-api/storage/useStorage.mjs';
-export { useLocalStorage } from './browser-api/storage/useLocalStorage.mjs';
-export { useSessionStorage } from './browser-api/storage/useSessionStorage.mjs';
-export { useIsPortrait } from './browser-api/useIsPortrait.mjs';
-export { useMediaQuery } from './browser-api/useMediaQuery.mjs';
-export { useFocusTrap } from './dom-api/useFocusTrap.mjs';
-export { useScrollBlock } from './dom-api/useScrollBlock.mjs';
-export { useIsClient } from './misc/useIsClient.mjs';
-export { useIsFirstRender } from './misc/useIsFirstRender.mjs';
-export { useUpdateEffect } from './misc/useUpdateEffect.mjs';
-import 'react';
+import * as react from 'react';
+type Value<T> = T | undefined | null;
+type SetValue<T> = React.Dispatch<React.SetStateAction<T>>;
+/**
+ * Easly handle Local or Session Storage State.
+ *
+ * @param	key		The storage item key.
+ * @param	initial	The storage item initial value.
+ * @param	type	( Optional ) The storage API to use. Default: `local`.
+ */
+declare const useStorage: <T = string>(key: string, initial?: T, type?: "local" | "session") => [Value<T>, SetValue<Value<T>>];
+/**
+ * useLocalStorage hook.
+ *
+ * @param	key		The local storage item key.
+ * @param	initial	The local storage item initial value.
+ */
+declare const useLocalStorage: <T = string>(key: string, initial?: T) => [T | null | undefined, (value: react.SetStateAction<T | null | undefined>) => void];
+/**
+ * useSessionStorage hook.
+ *
+ * @param	key		The session item key.
+ * @param	initial	The session item initial value.
+ */
+declare const useSessionStorage: <T = string>(key: string, initial?: T) => [T | null | undefined, (value: react.SetStateAction<T | null | undefined>) => void];
+interface UseDarkModeOutput {
+    /**
+     * Indicates whether dark mode is enabled.
+     *
+     */
+    isDarkMode: boolean;
+    /**
+     * Indicates whether the current device prefers dark theme.
+     *
+     */
+    isDarkOS: boolean;
+    /**
+     * Toggle dark mode.
+     *
+     */
+    toggleDarkMode: () => void;
+    /**
+     * Enable dark mode.
+     *
+     */
+    enableDarkMode: () => void;
+    /**
+     * Disable dark mode.
+     *
+     */
+    disableDarkMode: () => void;
+}
+interface UseDarkModeOptions {
+    /**
+     * The fallback value to use if no preference is saved in `localStorage`.
+     *
+     * @default
+     *
+     * true	// if device prefers dark color scheme.
+     * false	// if device prefers light color scheme.
+     *
+     */
+    initial?: boolean;
+    /**
+     * Array of class names to toggle on the `<html>` element, e.g. `['dark', 'light']`.
+     *
+     */
+    docClassNames?: [dark: string, light: string];
+}
+/**
+ * Easily manage dark mode with full respect for user device preferences.
+ *
+ * This hook is user-oriented and built to honor system-level color scheme settings:
+ *
+ * - If the device prefers a dark color scheme, dark mode is automatically enabled on first load.
+ * - If the user enables/disables dark mode via a web widget, the preference is stored in `localStorage` under the key `dark-mode`.
+ * - If the device color scheme preference changes (e.g. via OS settings), that change takes precedence and is stored for future visits.
+ *
+ * @param options Configuration object for the hook. See {@link UseDarkModeOptions} for more info.
+ *
+ * @returns	An object containing utilities for managing dark mode.
+ */
+declare const useDarkMode: (options?: UseDarkModeOptions) => UseDarkModeOutput;
+/**
+ * Specifies characteristics about the event listener.
+ *
+ * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#options)
+ */
+interface AddEventListenerOptions {
+    /**
+     * A boolean value indicating that events of this type will be dispatched to the registered
+     * listener before being dispatched to any `EventTarget`beneath it in the DOM tree.
+     *
+     * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#capture)
+     *
+     * @default false
+     */
+    capture?: boolean;
+    /**
+     * A boolean value indicating that the listener should be invoked at most once after being added.
+     * If `true`, the listener would be automatically removed when invoked.
+     *
+     * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#once)
+     *
+     * @default false
+     */
+    once?: boolean;
+    /**
+     * A boolean value that, if `true`, indicates that the function specified by `listener`
+     * will never call [`preventDefault()`](https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault).
+     * If a passive listener calls `preventDefault()`, nothing will happen and a console warning may be generated.
+     *
+     * If this option is not specified it defaults to `false` – except that in browsers other than Safari,
+     * it defaults to `true` for [`wheel`](https://developer.mozilla.org/en-US/docs/Web/API/Element/wheel_event),
+     * [`mousewheel`](https://developer.mozilla.org/en-US/docs/Web/API/Element/mousewheel_event),
+     * [`touchstart`](https://developer.mozilla.org/en-US/docs/Web/API/Element/touchstart_event) and
+     * [`touchmove`](https://developer.mozilla.org/en-US/docs/Web/API/Element/touchmove_event) events.
+     *
+     * See [Using passive listeners](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#using_passive_listeners) to learn more.
+     *
+     * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#passive)
+     */
+    passive?: boolean;
+    /**
+     * An [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal).
+     * The listener will be removed when the
+     * [`abort()`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort) method
+     * of the [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) which
+     * owns the `AbortSignal` is called. If not specified, no `AbortSignal` is associated with the listener.
+     *
+     * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#signal)
+     */
+    signal?: AbortSignal;
+}
+/**
+ * The `addEventListener` options.
+ *
+ * - If `boolean` is given, indicates whether events of this type will be dispatched to the registered
+ * listener before being dispatched to any EventTarget beneath it in the DOM tree. See [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#usecapture).
+ * - If an object is given, it specifies characteristics about the event listener. See [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#options).
+ */
+type ListenerOptions = boolean | AddEventListenerOptions;
+/**
+ * The Window Event listener.
+ *
+ * @param event The event object that implements the [`Event`](https://developer.mozilla.org/en-US/docs/Web/API/Event) interface.
+ */
+type WindowEventListener<K extends keyof WindowEventMap> = (event: WindowEventMap[K]) => void;
+/**
+ * The Document Event listener.
+ *
+ * @param event The event object that implements the [`Event`](https://developer.mozilla.org/en-US/docs/Web/API/Event) interface.
+ */
+type DocumentEventListener<K extends keyof DocumentEventMap> = (event: DocumentEventMap[K]) => void;
+/**
+ * The MediaQueryList Event listener.
+ *
+ * @param event The [`MediaQueryListEvent`](https://developer.mozilla.org/en-US/docs/Web/API/MediaQueryListEvent) object.
+ */
+type MediaQueryEventListener<K extends keyof MediaQueryListEventMap> = (event: MediaQueryListEventMap[K]) => void;
+/**
+ * The MediaQueryList "change" Event listener.
+ *
+ * @param event The [`MediaQueryListEvent`](https://developer.mozilla.org/en-US/docs/Web/API/MediaQueryListEvent) object.
+ */
+type MediaQueryChangeListener = (event: MediaQueryListEventMap['change']) => void;
+/**
+ * The HTMLElement Event listener.
+ *
+ * @param event The event object that implements the [`Event`](https://developer.mozilla.org/en-US/docs/Web/API/Event) interface.
+ */
+type ElementEventListener<K extends keyof HTMLElementEventMap> = (event: HTMLElementEventMap[K]) => void;
+interface CommonListenerOptions {
+    /**
+     * A custom callback executed before event listener get attached.
+     *
+     */
+    onLoad?: () => void;
+    /**
+     * A custom callback executed after event listener get removed.
+     *
+     */
+    onCleanUp?: () => void;
+    /**
+     * Specifies characteristics about the event listener.
+     *
+     * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#options)
+     */
+    options?: ListenerOptions;
+}
+interface WindowListenerOptions<K extends keyof WindowEventMap> extends CommonListenerOptions {
+    /**
+     * The Window Event listener.
+     *
+     * @param event The event object that implements the [`Event`](https://developer.mozilla.org/en-US/docs/Web/API/Event) interface.
+     */
+    listener: WindowEventListener<K>;
+}
+interface DocumentListenerOptions<K extends keyof DocumentEventMap> extends CommonListenerOptions {
+    /**
+     * The `Document` reference or a React RefObject of the `Document`.
+     *
+     */
+    target: Document | null | React.RefObject<Document | null>;
+    /**
+     * The Document Event listener.
+     *
+     * @param event The event object that implements the [`Event`](https://developer.mozilla.org/en-US/docs/Web/API/Event) interface.
+     */
+    listener: DocumentEventListener<K>;
+}
+interface MediaQueryListenerOptions extends CommonListenerOptions {
+    /**
+     * The Media Query string to check.
+     *
+     */
+    query: string;
+    /**
+     * The MediaQueryList Event listener.
+     *
+     * @param event The [`MediaQueryListEvent`](https://developer.mozilla.org/en-US/docs/Web/API/MediaQueryListEvent) object.
+     */
+    listener: MediaQueryChangeListener;
+}
+interface ElementListenerOptions<T extends HTMLElement, K extends keyof HTMLElementEventMap> extends CommonListenerOptions {
+    /**
+     * The React RefObject of the target where the listener get attached to.
+     *
+     */
+    target: T | React.RefObject<T | null>;
+    /**
+     * The HTMLElement Event listener.
+     *
+     * @param event The event object that implements the [`Event`](https://developer.mozilla.org/en-US/docs/Web/API/Event) interface.
+     */
+    listener: ElementEventListener<K>;
+}
+interface CustomEventListenerOptions<T extends Record<string, Event>, K extends keyof T = keyof T> extends CommonListenerOptions {
+    /**
+     * The target where the listener get attached to.
+     *
+     * If not set, the listener will get attached to the `Window` object.
+     */
+    target?: Document | HTMLElement | null | React.RefObject<Document | HTMLElement | null>;
+    /**
+     * The Event listener.
+     *
+     * @param event The event object that implements the [`Event`](https://developer.mozilla.org/en-US/docs/Web/API/Event) interface.
+     */
+    listener: (event: T[K]) => void;
+}
+/**
+ * Attach a new Event listener to the `Window` object.
+ *
+ * @param type		The `Window` event name or an array of event names.
+ * @param options	An object defining init options. See {@link WindowListenerOptions} for more info.
+ *
+ * @example
+ *
+ * #### Add a new `Window` event listener
+ *
+ * ```ts
+ * useEventListener( 'scroll', {
+ * 	listener: useCallback( () => {
+ * 		console.log( window.scrollY )
+ * 	}, [] )
+ * } )
+ * ```
+ *
+ * ---
+ *
+ * #### Add multiple `Window` event listeners
+ *
+ * ```ts
+ * useEventListener( [ 'scroll', 'resize' ], {
+ * 	listener: useCallback( event => {
+ * 		console.log( event )
+ * 	}, [] )
+ * } )
+ * ```
+ */
+declare function useEventListener<K extends keyof WindowEventMap>(type: K | K[], options: WindowListenerOptions<K>): void;
+/**
+ * Attach a new Event listener to the `Document` object.
+ *
+ * @param type		The `Document` event name or an array of event names.
+ * @param options	An object defining init options. See {@link DocumentListenerOptions} for more info.
+ *
+ * @example
+ *
+ * #### Add a new `Document` event listener
+ *
+ * ```ts
+ * // A React.RefObject<Document | null> can be used too.
+ * const documentRef = useRef( typeof document !== 'undefined' ? document : null )
+ *
+ * useEventListener( 'visibilitychange', {
+ * 	target  : typeof document !== 'undefined' ? document : null, // or `documentRef`
+ * 	listener: useCallback( () => {
+ * 		console.log( document.visibilityState )
+ * 	}, [] )
+ * } )
+ * ```
+ *
+ * ---
+ *
+ * #### Add multiple `Document` event listeners
+ *
+ * ```ts
+ * useEventListener( [ 'visibilitychange', 'dblclick' ], {
+ * 	target  : typeof document !== 'undefined' ? document : null,
+ * 	listener: useCallback( ( event ) => {
+ * 		console.log( event )
+ * 	}, [] )
+ * } )
+ * ```
+ */
+declare function useEventListener<K extends keyof DocumentEventMap>(type: K | K[], options: DocumentListenerOptions<K>): void;
+/**
+ * Attach a new Event listener to a `HTMLElement` object.
+ *
+ * @param type		The `HTMLElement` event name or an array of event names.
+ * @param options	An object defining init options. See {@link ElementListenerOptions} for more info.
+ *
+ * @example
+ *
+ * #### Add a new `HTMLElement` event listener
+ *
+ * ```tsx
+ * 'use client'
+ *
+ * const Component: React.FC = () => {
+ *
+ * 	const elementRef = useRef<HTMLButtonElement>( null )
+ *
+ * 	useEventListener( 'click', {
+ * 		target  : elementRef,
+ * 		listener: useCallback( event => {
+ * 			console.log( event )
+ * 		}, [] )
+ * 	} )
+ *
+ * 	return (
+ * 		<button ref={ elementRef }>Click me</button>
+ * 	)
+ *
+ * }
+ * ```
+ *
+ * ---
+ *
+ * #### Add multiple `HTMLElement` event listeners
+ *
+ * ```tsx
+ * 'use client'
+ *
+ * const Component: React.FC = () => {
+ *
+ * 	const elementRef = useRef<HTMLButtonElement>( null )
+ *
+ * 	useEventListener( [ 'click', 'touchmove' ], {
+ * 		target  : elementRef,
+ * 		listener: useCallback( event => {
+ * 			console.log( event )
+ * 		}, [] )
+ * 	} )
+ *
+ * 	return (
+ * 		<button ref={ elementRef }>Click me</button>
+ * 	)
+ *
+ * }
+ * ```
+ */
+declare function useEventListener<T extends HTMLElement, K extends keyof HTMLElementEventMap>(type: K | K[], options: ElementListenerOptions<T, K>): void;
+/**
+ * Listen MediaQuery changes.
+ *
+ * @param type		The `MediaQueryList` event name or an array of event names.
+ * @param options	An object defining init options. See {@link MediaQueryListenerOptions} for more info.
+ *
+ * @example
+ *
+ * #### Listen for MediaQuery changes.
+ *
+ * ```ts
+ * useEventListener( 'change', {
+ * 	query   : '(max-width: 768px)',
+ * 	listener: useCallback( event => {
+ * 		console.error( event.matches )
+ * 	}, [] ),
+ * } )
+ * ```
+ */
+declare function useEventListener(type: 'change', options: MediaQueryListenerOptions): void;
+/**
+ * Attach a new custom Event listener to the given target.
+ *
+ * @param type		The custom event name or an array of event names.
+ * @param options	An object defining init options. See {@link CustomEventListenerOptions} for more info.
+ *
+ * @example
+ *
+ * #### Add a new custom event listener
+ *
+ * ```tsx
+ * 'use client'
+ *
+ * const Component: React.FC = () => {
+ *
+ * 	const elementRef = useRef<HTMLButtonElement>( null )
+ *
+ * 	useEventListener( 'customevent', {
+ * 		target  : elementRef, // could be document. window will be used if omitted.
+ * 		listener: useCallback( event => {
+ * 			console.log( event )
+ * 		}, [] )
+ * 	} )
+ *
+ * 	useEffect( () => {
+ * 		elementRef.current?.dispatchEvent( new Event( 'customevent' ) )
+ * 	}, [] )
+ *
+ * 	return (
+ * 		<button ref={ elementRef }>Button</button>
+ * 	)
+ *
+ * }
+ * ```
+ *
+ * ---
+ *
+ * #### Adding types for custom events
+ *
+ * ```tsx
+ * interface Details
+ * {
+ * 	property?: string
+ * }
+ *
+ * type CustomEventMap = {
+ * 	customevent		: CustomEvent<Details>
+ * 	anothercustomEvent	: MouseEvent
+ * }
+ *
+ * type CustomEventType = keyof CustomEventMap
+ * const elementRef = useRef<HTMLButtonElement>( null )
+ * const eventType: CustomEventType = 'anothercustomEvent'
+ *
+ * useEventListener<CustomEventMap, typeof eventType>( eventType, {
+ * 	target  : elementRef,
+ * 	listener: useCallback( event => {
+ * 		console.log( event )
+ * 	}, [] )
+ * } )
+ *
+ * useEffect( () => {
+ *
+ * 	elementRef.current?.dispatchEvent( new CustomEvent<Details>( 'customevent', {
+ * 		detail: {
+ * 			property: 'value'
+ * 		}
+ * 	} ) )
+ *
+ * }, [] )
+ *```
+ */
+declare function useEventListener<T extends Record<string, Event>, K extends keyof T = keyof T>(type: K | K[], options: CustomEventListenerOptions<T, K>): void;
+/**
+ * Check if device is portrait oriented.
+ *
+ * State get updated when device orientation changes.
+ *
+ * @returns	`true` if the device is portrait oriented, `false` otherwise.
+ */
+declare const useIsPortrait: () => boolean;
+/**
+ * Get Document Media matches and listen for changes.
+ *
+ * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/Window/matchMedia)
+ *
+ * @param	query A string specifying the media query to parse into a `MediaQueryList`.
+ * @returns	A boolean value that returns `true` if the document currently matches the media query list, or `false` if not.
+ */
+declare const useMediaQuery: (query: string) => boolean;
+type SetFocusTrap = (target?: HTMLElement) => void;
+type RestoreFocusTrap = () => void;
+/**
+ * Trap focus inside the given HTML Element.
+ *
+ * @param target (Optional) The target HTMLElement React RefObject to trap focus within.
+ * 					If no target is given, you must provide the target HTMLElement when calling `setFocusTrap`.
+ *
+ * @returns A tuple containing:
+ * - `setFocusTrap`: A function to enable the focus trap. Optionally accept an HTMLElement as target.
+ * - `restoreFocusTrap`: A function to restore the previous focus state.
+ */
+declare const useFocusTrap: (target?: React.RefObject<HTMLElement | null>) => readonly [SetFocusTrap, RestoreFocusTrap];
+type MarginValue = `${number}${'px' | '%'}`;
+type MarginType = (MarginValue | `${MarginValue} ${MarginValue}` | `${MarginValue} ${MarginValue} ${MarginValue}` | `${MarginValue} ${MarginValue} ${MarginValue} ${MarginValue}`);
+/**
+ * A custom callback executed when target element's visibility has crossed one or more thresholds.
+ *
+ * This callback is awaited before any state update.
+ *
+ * If an error is thrown the React State update won't be fired.
+ *
+ * ⚠️ Wrap your callback with `useCallback` to avoid unnecessary `IntersectionObserver` recreation.
+ *
+ * @param	entry		The intersecting {@link IntersectionObserverEntry}.
+ * @param	observer	The current {@link IntersectionObserver} instance.
+ */
+type OnStartHandler = (entry: IntersectionObserverEntry, observer: IntersectionObserver) => void | Promise<void>;
+interface UseInViewOptions {
+    /**
+     * Identifies the {@link Element} or {@link Document} whose bounds are treated as the bounding box of the viewport for the Element which is the observer's target.
+     *
+     * If the `root` is `null`, then the bounds of the actual document viewport are used.
+     *
+     * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/root)
+     */
+    root?: Element | Document | false | null;
+    /**
+     * A string, formatted similarly to the CSS margin property's value, which contains offsets for one or more sides of the root's bounding box.
+     *
+     * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/rootMargin)
+     */
+    margin?: MarginType;
+    /**
+     * The intersecting target thresholds.
+     *
+     * Threshold can be set to:
+     * - `all` - `1` will be used.
+     * - `some` - `0.5` will be used.
+     * - `number`
+     * - `number[]`
+     *
+     * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/thresholds)
+     */
+    amount?: 'all' | 'some' | number | number[];
+    /**
+     * By setting this to `true` the observer will be disconnected after the target Element enters the viewport.
+     *
+     * Consider using a placeholder to avoid layout shifts while mounting/unmounting components when `once` is set to `false`.
+     */
+    once?: boolean;
+    /**
+     * Initial value.
+     *
+     * @default true
+     */
+    initial?: boolean;
+    /**
+     * Defines the initial observation activity. Use {@link UseInViewReturnType.setEnabled} to update this state.
+     *
+     * @default true
+     */
+    enable?: boolean;
+    /**
+     * A custom callback executed when target element's visibility has crossed one or more thresholds.
+     *
+     * This callback is awaited before any state update.
+     *
+     * If an error is thrown the React State update won't be fired.
+     *
+     * ⚠️ Wrap your callback with `useCallback` to avoid unnecessary `IntersectionObserver` recreation.
+     *
+     * @param	entry		The intersecting {@link IntersectionObserverEntry}.
+     * @param	observer	The current {@link IntersectionObserver} instance.
+     */
+    onStart?: OnStartHandler;
+}
+interface UseInViewReturnType {
+    /**
+     * Indicates whether the target Element is in viewport or not.
+     *
+     */
+    inView: boolean;
+    /**
+     * Indicates whether the target Element is being observed or not.
+     *
+     */
+    enabled: boolean;
+    /**
+     * The {@link IntersectionObserver} instance.
+     *
+     * It could be `undefined` if `IntersectionObserver` is not available or observation is not enabled.
+     *
+     * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver)
+     */
+    observer?: IntersectionObserver;
+    /**
+     * A React Dispatch SetState action that allows custom state updates.
+     *
+     */
+    setInView: React.Dispatch<React.SetStateAction<boolean>>;
+    /**
+     * A React Dispatch SetState action that allows to enable/disable observation when needed.
+     *
+     */
+    setEnabled: React.Dispatch<React.SetStateAction<boolean>>;
+}
+/**
+ * Check if the given target Element is intersecting with an ancestor Element or with a top-level document's viewport.
+ *
+ * @param	target	The React.RefObject of the target Element to observe.
+ * @param	options ( Optional ) An object defining custom {@link IntersectionObserver} options. See {@link UseInViewOptions} for more info.
+ *
+ * @returns An object defining intersection data. See {@link UseInViewReturnType} for more info.
+ */
+declare const useInView: (target: React.RefObject<Element | null>, options?: UseInViewOptions) => UseInViewReturnType;
+/**
+ * Prevent Element overflow.
+ *
+ * @param target (Optional) The React RefObject target HTMLElement. Default: `Document.documentElement`.
+ */
+declare const useScrollBlock: (target?: React.RefObject<HTMLElement | null>) => readonly [() => void, () => void];
+/**
+ * Check if the React Hook or Component where this hook is executed is running in a browser environment.
+ *
+ * @returns `true` if the React Hook or Component is running in a browser environment, `false` otherwise.
+ */
+declare const useIsClient: () => boolean;
+/**
+ * Check if is first React Hook/Component render.
+ *
+ * @returns `true` at the mount time, then always `false`.
+ * - Note that if the React Hook/Component has no state updates, `useIsFirstRender` will always return `true`.
+ */
+declare const useIsFirstRender: () => boolean;
+/**
+ * Modified version of `useEffect` that skips the first render.
+ *
+ * @param	effect	Imperative function that can return a cleanup function.
+ * @param	deps	If present, effect will only activate if the values in the list change.
+ */
+declare const useUpdateEffect: (effect: React.EffectCallback, deps?: React.DependencyList) => void;
+/**
+ * The function called when the timer elapses.
+ *
+ */
+type TimerHandler<T extends readonly unknown[]> = ((...args: T) => void) | (() => void);
+/**
+ * The Timer Id return by `setTimeout` or `setInterval` functions
+ *
+ */
+type TimerId = number | NodeJS.Timeout;
+/**
+ * Start the timer.
+ *
+ * @returns The {@link TimerId}.
+ */
+type StartTimer = () => TimerId;
+/**
+ * Stop the timer.
+ *
+ */
+type StopTimer = () => void;
+interface BasicTimerOptions<T extends readonly unknown[]> {
+    /**
+     * The number of milliseconds to wait before calling the `callback`.
+     *
+     * @default 1
+     */
+    delay?: number;
+    /**
+     * Optional arguments to pass when the `callback` is called.
+     *
+     * Make sure to memoize its value to avoid timer restarts when a state update happen in your Component.
+     */
+    args?: T;
+}
+interface TimerOptions<T extends readonly unknown[]> extends BasicTimerOptions<T> {
+    /**
+     * Indicates whether auto start the timer.
+     *
+     * @default true
+     */
+    autoplay?: boolean;
+    /**
+     * Whether to update React state about Timer running status.
+     *
+     * @default false
+     */
+    updateState?: boolean;
+    /**
+     * Indicates whether to execute the callback when timer starts.
+     *
+     * @default false
+     */
+    runOnStart?: boolean;
+}
+interface StateTimerOptions<T extends readonly unknown[]> extends TimerOptions<T> {
+    /**
+     * Whether to update React state about Timer running status.
+     *
+     * @default false
+     */
+    updateState: true;
+}
+interface TimerReturnType {
+    /**
+     * Manually start the timer.
+     *
+     * @returns The Timer ID.
+     */
+    start: StartTimer;
+    /**
+     * Manually stop the timer.
+     *
+     */
+    stop: StopTimer;
+}
+interface StateTimerReturnType extends TimerReturnType {
+    /**
+     * Indicates whether the timer is active.
+     *
+     */
+    isActive: boolean;
+}
+/**
+ * Debounce a value by a specified delay.
+ *
+ * This hook returns a debounced version of the input value, which only updates
+ * after the specified delay has passed without any changes to the input value.
+ * It is useful for scenarios like search input fields or other cases where
+ * frequent updates should be minimized.
+ *
+ * The `Timeout` automatically restarts when the given `value` changes.
+ *
+ * @template T The type of the `value`.
+ *
+ * @param value The value to debounce. This can be of any type.
+ * @param delay The debounce delay in milliseconds. Default `500`.
+ *
+ * @returns The debounced value, which updates only after the delay has passed.
+ */
+declare const useDebounce: <T>(value: T, delay?: number) => T;
+/**
+ * Schedules repeated execution of `callback` every `delay` milliseconds.
+ *
+ * A React State update will occur when the timer expires or get cancelled by `stop()` method.
+ *
+ * When `delay` is larger than `2147483647` or less than `1` or `NaN`, the `delay`
+ * will be set to `1`. Non-integer delays are truncated to an integer.
+ *
+ * If `callback` is not a function, a `TypeError` will be thrown.
+ *
+ * The `Timeout` is automatically cancelled on unmount.
+ *
+ * @template T An Array defining optional arguments passed to the `callback`.
+ *
+ * @param	callback	The function to call when the timer elapses.
+ * @param	options		(Optional) An object defining custom timer options. See {@link StateTimerOptions} for more info.
+ *
+ * @returns An object with timer utilities. See {@link StateTimerReturnType} for more info.
+ */
+declare function useInterval<T extends readonly unknown[]>(callback: TimerHandler<T>, options?: StateTimerOptions<T>): StateTimerReturnType;
+/**
+ * Schedules repeated execution of `callback` every `delay` milliseconds.
+ *
+ * When `delay` is larger than `2147483647` or less than `1` or `NaN`, the `delay`
+ * will be set to `1`. Non-integer delays are truncated to an integer.
+ *
+ * If `callback` is not a function, a `TypeError` will be thrown.
+ *
+ * The `Timeout` is automatically cancelled on unmount.
+ *
+ * @template T An Array defining optional arguments passed to the `callback`.
+ *
+ * @param	callback	The function to call when the timer elapses.
+ * @param	options		(Optional) An object defining custom timer options. See {@link TimerOptions} for more info.
+ *
+ * @returns An object with timer utilities. See {@link TimerReturnType} for more info.
+ */
+declare function useInterval<T extends readonly unknown[]>(callback: TimerHandler<T>, options?: TimerOptions<T>): TimerReturnType;
+/**
+ * Schedules repeated execution of `callback` every `delay` milliseconds.
+ *
+ * This is a lighter version of [`useInterval`](./useInterval.ts), suggested to use when
+ * a basic functionality is enough (no manual start/stop or state updates).
+ *
+ * When `delay` is larger than `2147483647` or less than `1` or `NaN`, the `delay`
+ * will be set to `1`. Non-integer delays are truncated to an integer.
+ *
+ * If `callback` is not a function, a `TypeError` will be thrown.
+ *
+ * The `Timeout` is automatically cancelled on unmount.
+ *
+ * @template T An Array defining optional arguments passed to the `callback`.
+ *
+ * @param	callback	The function to call when the timer elapses.
+ * @param	options		(Optional) An object defining custom timer options. See {@link BasicTimerOptions} for more info.
+ */
+declare const useLightInterval: <T extends readonly unknown[]>(callback: TimerHandler<T>, options?: BasicTimerOptions<T>) => void;
+interface UseIntervalWhenVisibleReturnType extends Omit<TimerReturnType, 'start'> {
+    /**
+     * Manually start the timer.
+     *
+     * @returns The Timer ID if Document is visible.
+     */
+    start: () => TimerId | undefined;
+}
+interface UseIntervalWhenVisibleStateReturnType extends Omit<StateTimerReturnType, 'start'> {
+    /**
+     * Manually start the timer.
+     *
+     * @returns The Timer ID if Document is visible.
+     */
+    start: () => TimerId | undefined;
+    /**
+     * Indicates that the timer is active, thus the Document is visible.
+     *
+     */
+    isActive: boolean;
+}
+/**
+ * Schedules repeated execution of `callback` every `delay` milliseconds when `Document` is visible.
+ *
+ * This hook automatically starts and stops the interval based on the `Document` visibility.
+ *
+ * The `Timeout` is automatically cancelled on unmount.
+ *
+ * @template T An Array defining optional arguments passed to the `callback`.
+ *
+ * @param	callback	The function to call when the timer elapses.
+ * @param	options		(Optional) An object defining custom timer options. See {@link StateTimerOptions} for more info.
+ *
+ * @returns An object with timer utilities. See {@link UseIntervalWhenVisibleStateReturnType} for more info.
+ */
+declare function useIntervalWhenVisible<T extends readonly unknown[]>(callback: TimerHandler<T>, options?: StateTimerOptions<T>): UseIntervalWhenVisibleStateReturnType;
+/**
+ * Schedules repeated execution of `callback` every `delay` milliseconds when `Document` is visible.
+ *
+ * This hook automatically starts and stops the interval based on the `Document` visibility.
+ *
+ * The `Timeout` is automatically cancelled on unmount.
+ *
+ * @template T An Array defining optional arguments passed to the `callback`.
+ *
+ * @param	callback	The function to call when the timer elapses.
+ * @param	options		(Optional) An object defining custom timer options. See {@link TimerOptions} for more info.
+ *
+ * @returns An object with timer utilities. See {@link UseIntervalWhenVisibleReturnType} for more info.
+ */
+declare function useIntervalWhenVisible<T extends readonly unknown[]>(callback: TimerHandler<T>, options?: TimerOptions<T>): UseIntervalWhenVisibleReturnType;
+/**
+ * Schedules execution of a one-time `callback` after `delay` milliseconds.
+ *
+ * A React State update will occur when the timer expires or get cancelled by `stop()` method.
+ *
+ * The `callback` will likely not be invoked in precisely `delay` milliseconds.
+ * Node.js makes no guarantees about the exact timing of when callbacks will fire,
+ * nor of their ordering. The callback will be called as close as possible to the
+ * time specified.
+ *
+ * When `delay` is larger than `2147483647` or less than `1` or `NaN`, the `delay`
+ * will be set to `1`. Non-integer delays are truncated to an integer.
+ *
+ * If `callback` is not a function, a `TypeError` will be thrown.
+ *
+ * The `Timeout` is automatically cancelled on unmount.
+ *
+ * @template T An Array defining optional arguments passed to the `callback`.
+ *
+ * @param	callback	The function to call when the timer elapses.
+ * @param	options		(Optional) An object defining custom timer options. See {@link StateTimerOptions} for more info.
+ *
+ * @returns An object with timer utilities. See {@link StateTimerReturnType} for more info.
+ */
+declare function useTimeout<T extends readonly unknown[]>(callback: TimerHandler<T>, options?: StateTimerOptions<T>): StateTimerReturnType;
+/**
+ * Schedules execution of a one-time `callback` after `delay` milliseconds.
+ *
+ * The `callback` will likely not be invoked in precisely `delay` milliseconds.
+ * Node.js makes no guarantees about the exact timing of when callbacks will fire,
+ * nor of their ordering. The callback will be called as close as possible to the
+ * time specified.
+ *
+ * When `delay` is larger than `2147483647` or less than `1` or `NaN`, the `delay`
+ * will be set to `1`. Non-integer delays are truncated to an integer.
+ *
+ * If `callback` is not a function, a `TypeError` will be thrown.
+ *
+ * The `Timeout` is automatically cancelled on unmount.
+ *
+ * @template T An Array defining optional arguments passed to the `callback`.
+ *
+ * @param	callback	The function to call when the timer elapses.
+ * @param	options		(Optional) An object defining custom timer options. See {@link TimerOptions} for more info.
+ *
+ * @returns An object with timer utilities. See {@link TimerReturnType} for more info.
+ */
+declare function useTimeout<T extends readonly unknown[]>(callback: TimerHandler<T>, options?: TimerOptions<T>): TimerReturnType;
+/**
+ * Schedules execution of a one-time `callback` after `delay` milliseconds.
+ *
+ * This is a lighter version of [`useTimeout`](./useTimeout.ts), suggested to use when
+ * a basic functionality is enough (no manual start/stop or state updates).
+ *
+ * The `callback` will likely not be invoked in precisely `delay` milliseconds.
+ * Node.js makes no guarantees about the exact timing of when callbacks will fire,
+ * nor of their ordering. The callback will be called as close as possible to the
+ * time specified.
+ *
+ * When `delay` is larger than `2147483647` or less than `1` or `NaN`, the `delay`
+ * will be set to `1`. Non-integer delays are truncated to an integer.
+ *
+ * If `callback` is not a function, a `TypeError` will be thrown.
+ *
+ * The `Timeout` is automatically cancelled on unmount.
+ *
+ * @template T An Array defining optional arguments passed to the `callback`.
+ *
+ * @param	callback	The function to call when the timer elapses.
+ * @param	options		(Optional) An object defining custom timer options. See {@link BasicTimerOptions} for more info.
+ */
+declare const useLightTimeout: <T extends readonly unknown[]>(callback: TimerHandler<T>, options?: BasicTimerOptions<T>) => void;
+export { type AddEventListenerOptions, type BasicTimerOptions, type CommonListenerOptions, type CustomEventListenerOptions, type DocumentEventListener, type DocumentListenerOptions, type ElementEventListener, type ElementListenerOptions, type ListenerOptions, type MarginType, type MarginValue, type MediaQueryChangeListener, type MediaQueryEventListener, type MediaQueryListenerOptions, type OnStartHandler, type StartTimer, type StateTimerOptions, type StateTimerReturnType, type StopTimer, type TimerHandler, type TimerId, type TimerOptions, type TimerReturnType, type UseDarkModeOptions, type UseDarkModeOutput, type UseInViewOptions, type UseInViewReturnType, type UseIntervalWhenVisibleReturnType, type UseIntervalWhenVisibleStateReturnType, type WindowEventListener, type WindowListenerOptions, useDarkMode, useDebounce, useEventListener, useFocusTrap, useInView, useInterval, useIntervalWhenVisible, useIsClient, useIsFirstRender, useIsPortrait, useLightInterval, useLightTimeout, useLocalStorage, useMediaQuery, useScrollBlock, useSessionStorage, useStorage, useTimeout, useUpdateEffect };