@siberiacancode/reactuse 0.2.28 → 0.2.30

package/dist/types/hooks/useAudio/useAudio.d.ts

@@ -39,7 +39,8 @@ export interface UseAudioReturn {
  * @name useAudio
  * @description - Hook that manages audio playback with sprite support
  * @category Browser
- *
+ * @usage low
+
  * @browserapi Audio https://developer.mozilla.org/en-US/docs/Web/API/Audio
  *
  * @template Value The type of the value

package/dist/types/hooks/useAutoScroll/useAutoScroll.d.ts

@@ -15,6 +15,7 @@ export interface UseAutoScroll {
  * @name useAutoScroll
  * @description - Hook that automatically scrolls a list element to the bottom
  * @category Elements
+ * @usage low
  *
  * @overload
  * @param {HookTarget} target The target element to auto-scroll

package/dist/types/hooks/useBattery/useBattery.d.ts

@@ -33,6 +33,7 @@ export interface UseBatteryStateReturn {
  * @name useBattery
  * @description - Hook for getting information about battery status
  * @category Browser
+ * @usage low
  *
  * @browserapi navigator.getBattery https://developer.mozilla.org/en-US/docs/Web/API/Navigator/getBattery
  *

package/dist/types/hooks/useBluetooth/useBluetooth.d.ts

@@ -24,6 +24,7 @@ export interface UseBluetoothOptions {
  * @name useBluetooth
  * @description - Hook for getting information about bluetooth
  * @category Browser
+ * @usage low
  *
  * @browserapi navigator.bluetooth https://developer.mozilla.org/en-US/docs/Web/API/Navigator/bluetooth
  *

package/dist/types/hooks/useBoolean/useBoolean.d.ts

@@ -9,7 +9,8 @@ export type UseBooleanReturn = [
  * @name useBoolean
  * @description - Hook provides opportunity to manage boolean state
  * @category State
- *
+ * @usage necessary
+
  * @param {boolean} [initialValue=false] The initial boolean value
  * @returns {UseBooleanReturn} An object containing the boolean state value and utility functions to manipulate the state
  *

package/dist/types/hooks/useBreakpoints/useBreakpoints.d.ts

@@ -33,6 +33,7 @@ export type UseBreakpointsReturn<Breakpoint extends string = string> = {
  * @name useBreakpoints
  * @description - Hook that manages breakpoints
  * @category Browser
+ * @usage medium
  *
  * @template {string} Breakpoint The name of the breakpoint
  * @param {Breakpoints<Breakpoint>} breakpoints The breakpoints to use

package/dist/types/hooks/useBroadcastChannel/useBroadcastChannel.d.ts

@@ -19,6 +19,7 @@ export interface UseBroadcastChannelReturn<Data = unknown> {
  * @name useBroadcastChannel
  * @description Hook that provides cross-tab/window communication
  * @category Browser
+ * @usage low
  *
  * @browserapi BroadcastChannel https://developer.mozilla.org/en-US/docs/Web/API/BroadcastChannel
  *

package/dist/types/hooks/useBrowserLanguage/useBrowserLanguage.d.ts

@@ -2,7 +2,8 @@
  * @name useBrowserLanguage
  * @description - Hook that returns the current browser language
  * @category User
- *
+ * @usage medium
+
  * @browserapi navigator.language https://developer.mozilla.org/en-US/docs/Web/API/Navigator/language
  *
  * @returns {string} The current browser language

package/dist/types/hooks/useClickOutside/useClickOutside.d.ts

@@ -8,7 +8,8 @@ export interface UseClickOutside {
  * @name useClickOutside
  * @description - Hook to handle click events outside the specified target element(s)
  * @category Elements
- *
+ * @usage necessary
+
  * @overload
  * @param {HookTarget} target The target element(s) to detect outside clicks for
  * @param {(event: Event) => void} callback The callback to execute when a click outside the target is detected

package/dist/types/hooks/useClipboard/useClipboard.d.ts

@@ -14,7 +14,8 @@ export interface UseCopyToClipboardParams {
  * @name useClipboard
  * @description - Hook that manages a copy to clipboard
  * @category Browser
- *
+ * @usage medium
+
  * @browserapi navigator.clipboard https://developer.mozilla.org/en-US/docs/Web/API/Navigator/clipboard
  *
  * @param {boolean} [params.enabled=false] Whether the copy to clipboard is enabled

package/dist/types/hooks/useConst/useConst.d.ts

@@ -2,7 +2,8 @@
  * @name useConst
  * @description - Hook that returns the constant value
  * @category Utilities
- *
+ * @usage high
+
  * @template Value The type of the value
  * @param {(() => Value) | Value} initialValue The initial value of the constant
  * @returns {Value} The constant value

package/dist/types/hooks/useCookie/useCookie.d.ts

@@ -55,7 +55,8 @@ export interface UseCookie {
  * @name useCookie
  * @description - Hook that manages cookie value
  * @category State
- *
+ * @usage medium
+
  * @overload
  * @template Value The type of the cookie value
  * @param {string} key The key of the cookie

package/dist/types/hooks/useCookies/useCookies.d.ts

@@ -10,7 +10,8 @@ export declare const clearCookies: () => void;
  * @name useCookies
  * @description - Hook that manages cookie values
  * @category State
- *
+ * @usage medium
+
  * @overload
  * @template {object} Value The type of the cookie values
  * @returns {UseCookieReturn<Value>} The value and the set function

package/dist/types/hooks/useCopy/useCopy.d.ts

@@ -16,7 +16,8 @@ export interface UseCopyParams {
  * @name useCopy
  * @description - Hook that manages copying text with status reset
  * @category Browser
- *
+ * @usage medium
+
  * @browserapi navigator.clipboard https://developer.mozilla.org/en-US/docs/Web/API/Navigator/clipboard
  *
  * @param {number} [delay=1000] Delay in ms before resetting copied status

package/dist/types/hooks/useCounter/useCounter.d.ts

@@ -29,7 +29,8 @@ export interface UseCounter {
  * @name useCounter
  * @description - Hook that manages a counter
  * @category State
- *
+ * @usage low
+
  * @overload
  * @param {number} [initialValue=0] The initial number value
  * @param {number} [options.min=Number.NEGATIVE_INFINITY] The min of count value

package/dist/types/hooks/useCssVar/useCssVar.d.ts

@@ -19,7 +19,8 @@ export interface UseCssVar {
  * @name useCssVar
  * @description - Hook that returns the value of a css variable
  * @category Browser
- *
+ * @usage low
+
  * @overload
  * @param {string} key The CSS variable key
  * @param {string} initialValue The initial value of the CSS variable

package/dist/types/hooks/useDebounceCallback/useDebounceCallback.d.ts

@@ -5,6 +5,7 @@ export type DebouncedCallback<Params extends unknown[]> = ((...args: Params) =>
  * @name useDebounceCallback
  * @description - Hook that creates a debounced callback
  * @category Utilities
+ * @usage high
  *
  * @template Params The type of the params
  * @template Return The type of the return

package/dist/types/hooks/useDebounceState/useDebounceState.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @name useDebounceState
+ * @description - Hook that creates a debounced state
+ * @category Utilities
+ * @usage high
+
+ * @template Value The type of the value
+ * @param {Value} value The value to be debounced
+ * @param {number} delay The delay in milliseconds
+ * @returns {[Value, (value: Value) => void]} The debounced state
+ *
+ * @example
+ * const [debouncedValue, setDebouncedValue] = useDebounceState(value, 500);
+ */
+export declare const useDebounceState: <Value>(initialValue: Value, delay: number) => readonly [Value, import('..').DebouncedCallback<[value: import('react').SetStateAction<Value>]>];

package/dist/types/hooks/useDebounceValue/useDebounceValue.d.ts

@@ -2,7 +2,8 @@
  * @name useDebounceValue
  * @description - Hook that creates a debounced value
  * @category Utilities
- *
+ * @usage high
+
  * @template Value The type of the value
  * @param {Value} value The value to be debounced
  * @param {number} delay The delay in milliseconds

package/dist/types/hooks/useDefault/useDefault.d.ts

@@ -2,7 +2,8 @@
  * @name useDefault
  * @description - Hook that returns the default value
  * @category State
- *
+ * @usage medium
+
  * @template Value The type of the value
  * @param {Value} initialValue The initial value
  * @param {Value} defaultValue The default value

package/dist/types/hooks/useDeviceMotion/useDeviceMotion.d.ts

@@ -15,7 +15,8 @@ export interface UseDeviceMotionParams {
 /**
  * @name useDeviceMotion
  * @description - Hook that work with device motion
- * @category Utilities
+ * @category Sensors
+ * @usage low
  *
  * @browserapi DeviceMotionEvent https://developer.mozilla.org/en-US/docs/Web/API/Window/DeviceMotionEvent
  *

package/dist/types/hooks/useDeviceOrientation/useDeviceOrientation.d.ts

@@ -18,6 +18,7 @@ export interface UseDeviceOrientationReturn {
  * @name useDeviceOrientation
  * @description - Hook that provides the current device orientation
  * @category Sensors
+ * @usage low
  *
  * @browserapi DeviceOrientationEvent https://developer.mozilla.org/en-US/docs/Web/API/Window/DeviceOrientationEvent
  *

package/dist/types/hooks/useDevicePixelRatio/useDevicePixelRatio.d.ts

@@ -9,6 +9,7 @@ export interface UseDevicePixelRatioReturn {
  * @name useDevicePixelRatio
  * @description - Hook that returns the device's pixel ratio
  * @category Utilities
+ * @usage low
  *
  * @browserapi window.devicePixelRatio https://developer.mozilla.org/en-US/docs/Web/API/Window/devicePixelRatio
  *

package/dist/types/hooks/useDidUpdate/useDidUpdate.d.ts

@@ -3,7 +3,8 @@ import { DependencyList, EffectCallback } from 'react';
  * @name useDidUpdate
  * @description – Hook that triggers the effect callback on updates
  * @category Lifecycle
- *
+ * @usage necessary
+
  * @param {EffectCallback} effect The effect callback
  * @param {DependencyList} [deps] The dependencies list for the effect
  *

package/dist/types/hooks/useDisclosure/useDisclosure.d.ts

@@ -20,7 +20,8 @@ export interface UseDisclosureReturn {
  * @name useDisclosure
  * @description - Hook that allows you to open and close a modal
  * @category State
- *
+ * @usage necessary
+
  * @param {boolean} [initialValue=false] The initial value of the component
  * @param {() => void} [options.onOpen] The callback function to be invoked on open
  * @param {() => void} [options.onClose] The callback function to be invoked on close

package/dist/types/hooks/useDisplayMedia/useDisplayMedia.d.ts

@@ -32,6 +32,7 @@ export interface UseDisplayMedia {
  * @name useDisplayMedia
  * @description - Hook that provides screen sharing functionality
  * @category Browser
+ * @usage low
  *
  * @browserapi mediaDevices.getDisplayMedia https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getDisplayMedia
  *

package/dist/types/hooks/useDocumentEvent/useDocumentEvent.d.ts

@@ -3,7 +3,8 @@ import { UseEventListenerOptions } from '../useEventListener/useEventListener';
  * @name useDocumentEvent
  * @description - Hook attaches an event listener to the document object for the specified event
  * @category Browser
- *
+ * @usage low
+
  * @template Event Key of document event map.
  * @param {Event} event The event to listen for.
  * @param {(event: DocumentEventMap[Event]) => void} listener The callback function to be executed when the event is triggered

package/dist/types/hooks/useDocumentTitle/useDocumentTitle.d.ts

@@ -14,7 +14,8 @@ export interface UseDocumentTitleReturn {
  * @name useDocumentTitle
  * @description - Hook that manages the document title and allows updating it
  * @category Browser
- *
+ * @usage low
+
  * @browserapi document.title https://developer.mozilla.org/en-US/docs/Web/API/Document/title
  *
  * @param {string} [initialValue] The initial title. If not provided, the current document title will be used

package/dist/types/hooks/useDocumentVisibility/useDocumentVisibility.d.ts

@@ -2,7 +2,8 @@
  * @name useDocumentVisibility
  * @description – Hook that provides the current visibility state of the document
  * @category Browser
- *
+ * @usage low
+
  * @returns {DocumentVisibilityState} The current visibility state of the document, which can be 'visible' or 'hidden'
  *
  * @example

package/dist/types/hooks/useDoubleClick/useDoubleClick.d.ts

@@ -17,7 +17,8 @@ export declare const DEFAULT_THRESHOLD_TIME = 300;
  * @name useDoubleClick
  * @description - Hook that defines the logic when double clicking an element
  * @category Elements
- *
+ * @usage medium
+
  * @overload
  * @param {HookTarget} target The target element to be double clicked
  * @param {(event: DoubleClickEvents) => void} callback The callback function to be invoked on double click

package/dist/types/hooks/useDropZone/useDropZone.d.ts

@@ -35,7 +35,8 @@ export interface UseDropZone {
  * @name useDropZone
  * @description - Hook that provides drop zone functionality
  * @category Elements
- *
+ * @usage medium
+
  * @overload
  * @template Target The target element
  * @param {Target} target The target element drop zone's

package/dist/types/hooks/useElementSize/useElementSize.d.ts

@@ -21,7 +21,8 @@ export interface UseElementSize {
  * @name useElementSize
  * @description - Hook that observes and returns the width and height of element
  * @category Elements
- *
+ * @usage low
+
  * @overload
  * @param {HookTarget} target The target element to observe
  * @returns {UseElementSizeReturn} An object containing the current width and height of the element

package/dist/types/hooks/useEvent/useEvent.d.ts

@@ -2,7 +2,8 @@
  * @name useEvent
  * @description - Hook that creates an event and returns a stable reference of it
  * @category Utilities
- *
+ * @usage high
+
  * @template Params The type of the params
  * @template Return The type of the return
  * @param {(...args: Params) => Return} callback The callback function

package/dist/types/hooks/useEventListener/useEventListener.d.ts

@@ -1,7 +1,9 @@
 import { HookTarget } from '../../utils/helpers';
 import { StateRef } from '../useRefState/useRefState';
 /** The use event listener options */
-export type UseEventListenerOptions = boolean | AddEventListenerOptions;
+export type UseEventListenerOptions = {
+    enabled?: boolean;
+} & AddEventListenerOptions;
 /** The use event listener return type */
 export type UseEventListenerReturn<Target extends Element> = StateRef<Target>;
 export interface UseEventListener {
@@ -15,7 +17,8 @@ export interface UseEventListener {
  * @name useEventListener
  * @description - Hook that attaches an event listener to the specified target
  * @category Browser
- *
+ * @usage necessary
+
  * @overload
  * @template Event Key of window event map
  * @param {Window} target The window object to attach the event listener to

package/dist/types/hooks/useEventSource/useEventSource.d.ts

@@ -32,6 +32,7 @@ interface UseEventSourceReturn<Data = any> {
  * @name useEventSource
  * @description - Hook that provides a reactive wrapper for event source
  * @category Browser
+ * @usage low
  *
  * @browserapi EventSource https://developer.mozilla.org/en-US/docs/Web/API/EventSource
  *

package/dist/types/hooks/useEyeDropper/useEyeDropper.d.ts

@@ -28,6 +28,7 @@ export interface UseEyeDropperReturn {
  * @name useEyeDropper
  * @description - Hook that gives you access to the eye dropper
  * @category Browser
+ * @usage low
  *
  * @browserapi EyeDropper https://developer.mozilla.org/en-US/docs/Web/API/EyeDropper
  *

package/dist/types/hooks/useFavicon/useFavicon.d.ts

@@ -5,12 +5,13 @@ export type UseFaviconReturn = [string, Dispatch<SetStateAction<string>>];
  * @name useFavicon
  * @description - Hook that manages the favicon
  * @category Browser
+ * @usage low
  *
  * @param {string} [initialFavicon] The initial favicon. If not provided, the current favicon will be used
  * @returns {UseFaviconReturn} An array containing the current favicon and a function to update the favicon
  *
  * @example
- * const { href, set } = useFavicon('https://www.google.com/favicon.ico');
+ * const { href, set } = useFavicon('https://siberiacancode.github.io/reactuse/favicon.ico');
  */
 export declare const useFavicon: (initialHref?: string) => {
     readonly href: string | undefined;

package/dist/types/hooks/useField/useField.d.ts

@@ -78,6 +78,7 @@ export interface UseFieldReturn<Value> {
  * @name useField
  * @description - Hook to manage a form field
  * @category State
+ * @usage medium
  *
  * @template Value The input value
  * @template Type The input value type

package/dist/types/hooks/useFileDialog/useFileDialog.d.ts

@@ -21,6 +21,7 @@ export interface UseFileDialog {
  * @name useFileDialog
  * @description - Hook to handle file input
  * @category Elements
+ * @usage low
  *
  * @overload
  * @param {(value: FileList | null) => void} callback The callback to execute when a file is selected

package/dist/types/hooks/useFocus/useFocus.d.ts

@@ -2,6 +2,8 @@ import { HookTarget } from '../../utils/helpers';
 import { StateRef } from '../useRefState/useRefState';
 /** The use focus options type */
 export interface UseFocusOptions {
+    /** The enabled state of the focus hook */
+    enabled?: boolean;
     /** The initial focus state of the target */
     initialValue?: boolean;
     /** The on blur callback */
@@ -19,7 +21,11 @@ export interface UseFocusReturn {
     focus: () => void;
 }
 export interface UseFocus {
+    (target: HookTarget, callback?: (event: FocusEvent) => void): UseFocusReturn;
     (target: HookTarget, options?: UseFocusOptions): UseFocusReturn;
+    <Target extends Element>(callback?: (event: FocusEvent) => void, target?: never): UseFocusReturn & {
+        ref: StateRef<Target>;
+    };
     <Target extends Element>(options?: UseFocusOptions, target?: never): UseFocusReturn & {
         ref: StateRef<Target>;
     };
@@ -28,9 +34,19 @@ export interface UseFocus {
  * @name useFocus
  * @description - Hook that allows you to focus on a specific element
  * @category Elements
+ * @usage medium
+ *
+ * @overload
+ * @param {HookTarget} target The target element to focus
+ * @param {(event: FocusEvent) => void} [callback] The callback function to be invoked on focus
+ * @returns {UseFocusReturn} An object with focus state and methods
+ *
+ * @example
+ * const { focus, blur, focused } = useFocus(ref, () => console.log('focused'));
  *
  * @overload
  * @param {HookTarget} target The target element to focus
+ * @param {boolean} [options.enabled=true] The enabled state of the focus hook
  * @param {boolean} [options.initialValue=false] The initial focus state of the target
  * @param {(event: FocusEvent) => void} [options.onFocus] The callback function to be invoked on focus
  * @param {(event: FocusEvent) => void} [options.onBlur] The callback function to be invoked on blur
@@ -41,6 +57,15 @@ export interface UseFocus {
  *
  * @overload
  * @template Target The target element
+ * @param {(event: FocusEvent) => void} [callback] The callback function to be invoked on focus
+ * @returns {UseFocusReturn & { ref: StateRef<Target> }} An object with focus state, methods and ref
+ *
+ * @example
+ * const { ref, focus, blur, focused } = useFocus(() => console.log('focused'));
+ *
+ * @overload
+ * @template Target The target element
+ * @param {boolean} [options.enabled=true] The enabled state of the focus hook
  * @param {boolean} [options.initialValue=false] The initial focus state of the target
  * @param {(event: FocusEvent) => void} [options.onFocus] The callback function to be invoked on focus
  * @param {(event: FocusEvent) => void} [options.onBlur] The callback function to be invoked on blur

package/dist/types/hooks/useFps/useFps.d.ts

@@ -2,6 +2,7 @@
  * @name useFps
  * @description - Hook that measures frames per second
  * @category Browser
+ * @usage low
  *
  * @browserapi requestAnimationFrame https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame
  *

package/dist/types/hooks/useFul/useFul.d.ts

@@ -2,6 +2,7 @@
  * @name useFul
  * @description - Hook that can be so useful
  * @category Humor
+ * @usage low
  *
  * @warning - This hook is a joke. Please do not use it in production code!
  *

package/dist/types/hooks/useFullscreen/useFullscreen.d.ts

@@ -30,6 +30,7 @@ export interface UseFullScreen {
  * @name useFullscreen
  * @description - Hook to handle fullscreen events
  * @category Browser
+ * @usage low
  *
  * @overload
  * @param {HookTarget} target The target element for fullscreen

package/dist/types/hooks/useGamepad/useGamepad.d.ts

@@ -16,6 +16,7 @@ export interface UseGamepadStateReturn {
  * @name useGamepad
  * @description - Hook for getting information about gamepad
  * @category Browser
+ * @usage low
  *
  * @browserapi navigator.getGamepads https://developer.mozilla.org/en-US/docs/Web/API/Navigator/getGamepads
  *

package/dist/types/hooks/useGeolocation/useGeolocation.d.ts

@@ -27,6 +27,7 @@ export type UseGeolocationParams = PositionOptions;
  * @name useGeolocation
  * @description - Hook that returns the current geolocation
  * @category Browser
+ * @usage medium
  *
  * @browserapi navigator.geolocation https://developer.mozilla.org/en-US/docs/Web/API/Navigator/geolocation
  *

package/dist/types/hooks/useHash/useHash.d.ts

@@ -4,6 +4,7 @@ type UseHashReturn = [string, (value: string) => void];
  * @name useHash
  * @description - Hook that manages the hash value
  * @category State
+ * @usage low
  *
  * @param {string} [initialValue] The initial hash value if no hash exists
  * @returns {UseHashReturn} An array containing the hash value and a function to set the hash value

package/dist/types/hooks/useHotkeys/useHotkeys.d.ts

@@ -28,6 +28,7 @@ export interface UseHotkeys {
  * @name useHotkeys
  * @description - Hook that listens for hotkeys
  * @category Sensors
+ * @usage medium
  *
  * @overload
  * @param {HookTarget} [target=window] The target element to attach the event listener to

package/dist/types/hooks/useHover/useHover.d.ts

@@ -2,6 +2,8 @@ import { HookTarget } from '../../utils/helpers';
 import { StateRef } from '../useRefState/useRefState';
 /** The use hover options type */
 export interface UseHoverOptions {
+    /** The enabled state of the hook */
+    enabled?: boolean;
     /** The on entry callback */
     onEntry?: (event: Event) => void;
     /** The on leave callback */
@@ -24,6 +26,7 @@ export interface UseHover {
  * @name useHover
  * @description - Hook that defines the logic when hovering an element
  * @category Elements
+ * @usage medium
  *
  * @overload
  * @param {HookTarget} target The target element to be hovered

package/dist/types/hooks/useIdle/useIdle.d.ts

@@ -16,6 +16,7 @@ export interface UseIdleReturn {
  * @name useIdle
  * @description - Hook that defines the logic when the user is idle
  * @category Sensors
+ * @usage low
  *
  * @param {number} [milliseconds=ONE_MINUTE] The idle time in milliseconds
  * @param {boolean} [options.initialState=false] The options for the hook

package/dist/types/hooks/useImage/useImage.d.ts

@@ -22,6 +22,7 @@ export type UseImageReturn = UseQueryReturn<HTMLImageElement>;
  * @name useImage
  * @description - Hook that load an image in the browser
  * @category Elements
+ * @usage low
  *
  * @param {string} src The source of the image
  * @param {string} [options.srcset] The srcset of the image

package/dist/types/hooks/useInfiniteScroll/useInfiniteScroll.d.ts

@@ -18,6 +18,7 @@ export interface UseInfiniteScroll {
  * @name useInfiniteScroll
  * @description - Hook that defines the logic for infinite scroll
  * @category Sensors
+ * @usage medium
  *
  * @overload
  * @template Target The target element