@siberiacancode/reactuse 0.2.29 → 0.2.31

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

@@ -19,6 +19,7 @@ export interface UseListReturn<Item> {
  * @name useList
  * @description - Hook that provides state and helper methods to manage a list of items
  * @category State
+ * @usage medium
  *
  * @template Item The type of the item
  * @param {Item[] | (() => Item[])} initialList The initial list of items

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

@@ -3,6 +3,7 @@ import { UseStorageInitialValue, UseStorageOptions } from '../useStorage/useStor
  * @name useLocalStorage
  * @description - Hook that manages local storage value
  * @category State
+ * @usage high
  *
  * @browserapi localStorage https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage
  *

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

@@ -2,6 +2,7 @@
  * @name useLockCallback
  * @description - Hook that prevents a callback from being executed multiple times simultaneously
  * @category Async
+ * @usage medium
  *
  * @param {Function} callback The callback to be locked
  * @returns {Function} The locked callback

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

@@ -28,7 +28,7 @@ export interface UseLockScroll {
  * @name useLockScroll
  * @description - Hook that locks scroll on an element or document body
  * @category Elements
- *
+ * @usage medium
  *
  * @overload
  * @param {HookTarget} [target=document.body] The target element to lock scroll on

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

@@ -2,6 +2,7 @@
  * @name useLogger
  * @description - Hook for debugging lifecycle
  * @category Debug
+ * @usage low
  *
  * @param {string} name The name or identifier for the logger
  * @param {unknown[]} params Additional arguments to be logged

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

@@ -18,6 +18,7 @@ export interface UseLongPress {
  * @name useLongPress
  * @description - Hook that defines the logic when long pressing an element
  * @category Elements
+ * @usage medium
  *
  * @overload
  * @param {HookTarget} target The target element to be long pressed

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

@@ -19,6 +19,7 @@ export interface UseMapReturn<Key, Value> {
  * @name useMap
  * @description - Hook that manages a map structure
  * @category State
+ * @usage high
  *
  * @template Value The type of the value
  * @param {Value[]} [values] The initial array of the map

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

@@ -12,6 +12,7 @@ export interface UseMeasure {
  * @name useMeasure
  * @description - Hook to measure the size and position of an element
  * @category Browser
+ * @usage low
  *
  * @overload
  * @param {HookTarget} target The element to measure

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

@@ -65,6 +65,7 @@ export interface UseMediaControls {
  * @name useMediaControls
  * @description Hook that provides controls for HTML media elements (audio/video)
  * @category Browser
+ * @usage low
  *
  * @overload
  * @param {HookTarget} target The target media element

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

@@ -2,6 +2,7 @@
  * @name useMediaQuery
  * @description - Hook that manages a media query
  * @category Browser
+ * @usage medium
  *
  * @browserapi window.matchMedia https://developer.mozilla.org/en-US/docs/Web/API/Window/matchMedia
  *

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

@@ -18,6 +18,7 @@ export interface UseMemoryReturn {
  * @name useMemory
  * @description - Hook that gives you current memory usage
  * @category Browser
+ * @usage low
  *
  * @browserapi performance.memory https://developer.mozilla.org/en-US/docs/Web/API/Performance/memory
  *

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

@@ -0,0 +1,17 @@
+import { Ref, RefCallback } from 'react';
+export declare const assignRef: <Element>(ref: Ref<Element>, value: Element) => ReturnType<RefCallback<Element>>;
+export declare const mergeRefs: <Element>(...refs: Ref<Element>[]) => RefCallback<Element>;
+/**
+ * @name useMergedRef
+ * @description - Hook that merges multiple refs into a single ref
+ * @category State
+ * @usage medium
+ *
+ * @template Element The element type
+ * @param {...Ref<Element>[]} refs The refs to merge
+ * @returns {RefCallback<Element>} A memoized ref callback that assigns to all provided refs
+ *
+ * @example
+ * const mergedRef = useMergedRef(firstRef, secondRef);
+ */
+export declare const useMergedRef: <Element>(...refs: Ref<Element>[]) => RefCallback<Element>;

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

@@ -3,6 +3,7 @@ import { EffectCallback } from 'react';
  * @name useMount
  * @description - Hook that executes a callback when the component mounts
  * @category Lifecycle
+ * @usage necessary
  *
  * @param {EffectCallback} effect The callback to execute
  *

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

@@ -30,6 +30,7 @@ export interface UseMouse {
  * @name useMouse
  * @description - Hook that manages a mouse position
  * @category Sensors
+ * @usage low
  *
  * @overload
  * @param {HookTarget} [target=window] The target element to manage the mouse position for

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

@@ -20,6 +20,7 @@ export interface RequestOptions<Data> extends UseMutationOptions<Data> {
  * @name useMutation
  * @description - Hook that defines the logic when mutate data
  * @category Async
+ * @usage high
  *
  * @template Body The type of the body
  * @template Data The type of the data

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

@@ -1,60 +1,77 @@
 import { HookTarget } from '../../utils/helpers';
 import { StateRef } from '../useRefState/useRefState';
-/** The mutation observer target element type */
-export type UseMutationObserverTarget = HookTarget;
-/** The mutation observer return type */
-export interface UseMutationObserverReturn {
-    /** The mutation observer instance */
-    observer: MutationObserver;
-    /** The mutation observer entries */
-    stop: () => void;
-}
+/** The mutation observer callback type */
+export type UseMutationObserverCallback = (mutations: MutationRecord[], observer: MutationObserver) => void;
 /** The mutation observer options type */
 export interface UseMutationObserverOptions extends MutationObserverInit {
     /** The enabled state of the mutation observer */
     enabled?: boolean;
+    /** The callback to execute when mutation is detected */
+    onChange?: UseMutationObserverCallback;
+}
+/** The mutation observer return type */
+export interface UseMutationObserverReturn {
+    /** The mutation observer instance */
+    observer?: MutationObserver;
 }
 export interface UseMutationObserver {
-    (target: HookTarget, callback: MutationCallback, options?: UseMutationObserverOptions): UseMutationObserverReturn;
-    <Target extends Element>(callback: MutationCallback, options?: UseMutationObserverOptions, target?: never): UseMutationObserverReturn & {
+    <Target extends Element>(options?: UseMutationObserverOptions, target?: never): UseMutationObserverReturn & {
+        ref: StateRef<Target>;
+    };
+    (target: HookTarget, options?: UseMutationObserverOptions): UseMutationObserverReturn;
+    <Target extends Element>(callback: UseMutationObserverCallback, target?: never): UseMutationObserverReturn & {
         ref: StateRef<Target>;
     };
+    (target: HookTarget, callback: UseMutationObserverCallback): UseMutationObserverReturn;
 }
 /**
  * @name useMutationObserver
  * @description - Hook that gives you mutation observer state
  * @category Sensors
+ * @usage low
+ *
+ * @browserapi MutationObserver https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver
  *
  * @overload
- * @template Target The target element
- * @param {MutationCallback} callback The callback to execute when mutation is detected
+ * @param {HookTarget} target The target element to observe
  * @param {boolean} [options.enabled=true] The enabled state of the mutation observer
+ * @param {UseMutationObserverCallback} [options.onChange] The callback to execute when mutation is detected
  * @param {boolean} [options.attributes] Set to true if mutations to target's attributes are to be observed
  * @param {boolean} [options.characterData] Set to true if mutations to target's data are to be observed
  * @param {boolean} [options.childList] Set to true if mutations to target's children are to be observed
- * @param {boolean} [options.subtree]  Set to true if mutations to not just target, but also target's descendants are to be observed
- * @param {boolean} [options.characterDataOldValue] Set to true if characterData is set to true or omitted and target's data before the mutation needs to be recorded
- * @param {boolean} [options.attributeOldValue]  Set to a list of attribute local names (without namespace) if not all attribute mutations need to be observed and attributes is true or omitted
- * @param {string[]} [options.attributeFilter] Set to a list of attribute local names (without namespace) if not all attribute mutations need to be observed and attributes is true or omitted
- * @returns {UseMutationObserverReturn & { ref: StateRef<Target> }} An object containing the mutation observer state
+ * @param {boolean} [options.subtree] Set to true if mutations to not just target, but also target's descendants are to be observed
+ * @returns {UseMutationObserverReturn} An object containing the mutation observer state
  *
  * @example
- * const { ref, observer, stop } = useMutationObserver(() => console.log('callback'))
+ * const { observer, stop } = useMutationObserver(ref, { childList: true });
  *
  * @overload
- * @param {HookTarget} target The target element to observe
- * @param {MutationCallback} callback The callback to execute when mutation is detected
+ * @template Target The target element
  * @param {boolean} [options.enabled=true] The enabled state of the mutation observer
+ * @param {UseMutationObserverCallback} [options.onChange] The callback to execute when mutation is detected
  * @param {boolean} [options.attributes] Set to true if mutations to target's attributes are to be observed
  * @param {boolean} [options.characterData] Set to true if mutations to target's data are to be observed
  * @param {boolean} [options.childList] Set to true if mutations to target's children are to be observed
- * @param {boolean} [options.subtree]  Set to true if mutations to not just target, but also target's descendants are to be observed
- * @param {boolean} [options.characterDataOldValue] Set to true if characterData is set to true or omitted and target's data before the mutation needs to be recorded
- * @param {boolean} [options.attributeOldValue]  Set to a list of attribute local names (without namespace) if not all attribute mutations need to be observed and attributes is true or omitted
- * @param {string[]} [options.attributeFilter] Set to a list of attribute local names (without namespace) if not all attribute mutations need to be observed and attributes is true or omitted
+ * @param {boolean} [options.subtree] Set to true if mutations to not just target, but also target's descendants are to be observed
+ * @returns {UseMutationObserverReturn & { ref: StateRef<Target> }} A React ref to attach to the target element
+ *
+ * @example
+ * const { ref, observer, stop } = useMutationObserver({ childList: true });
+ *
+ * @overload
+ * @template Target The target element
+ * @param {UseMutationObserverCallback} callback The callback to execute when mutation is detected
+ * @returns {UseMutationObserverReturn & { ref: StateRef<Target> }} A React ref to attach to the target element
+ *
+ * @example
+ * const { ref, observer, stop } = useMutationObserver((mutations) => console.log(mutations));
+ *
+ * @overload
+ * @param {UseMutationObserverCallback} callback The callback to execute when mutation is detected
+ * @param {HookTarget} target The target element to observe
  * @returns {UseMutationObserverReturn} An object containing the mutation observer state
  *
  * @example
- * const { observer, stop } = useMutationObserver(ref, () => console.log('callback'))
+ * const { observer, stop } = useMutationObserver((mutations) => console.log(mutations), ref);
  */
 export declare const useMutationObserver: UseMutationObserver;

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

@@ -40,6 +40,7 @@ export declare const getConnection: () => Connection;
  * @name useNetwork
  * @description - Hook to track network status
  * @category Browser
+ * @usage low
  *
  * @browserapi navigator.connection https://developer.mozilla.org/en-US/docs/Web/API/Navigator/connection
  *

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

@@ -23,6 +23,7 @@ export interface UseObjectReturn<Value extends object> {
  * @name useObject
  * @description - Hook that provides state and helper methods to manage an object
  * @category State
+ * @usage medium
  *
  * @template Value The type of the object
  * @param {Value} initialValue The initial object value

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

@@ -37,6 +37,7 @@ export interface UseOffsetPaginationReturn {
  * @name useOffsetPagination
  * @description - Hook that defines the logic when pagination
  * @category State
+ * @usage medium
  *
  * @param {UseOffsetPaginationOptions} options - The options for the hook
  * @param {number} [options.total] - The total number of items

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

@@ -3,6 +3,7 @@ import { EffectCallback } from 'react';
  * @name useEffectOnce
  * @description - Hook that runs an effect only once. Please do not use it in production code!
  * @category Humor
+ * @usage low
  *
  * @warning - This hook will run effect only once even in strict mode. Please do not use it in production code!
  *

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

@@ -2,6 +2,7 @@
  * @name useOnline
  * @description - Hook that manages if the user is online
  * @category Browser
+ * @usage medium
  *
  * @browserapi navigator.onLine https://developer.mozilla.org/en-US/docs/Web/API/Navigator/onLine
  *

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

@@ -5,6 +5,7 @@ export declare const getOperatingSystem: () => OperatingSystem;
  * @name useOperatingSystem
  * @description - Hook that returns the operating system of the current browser
  * @category User
+ * @usage low
  *
  * @returns {OperatingSystem} The operating system
  *

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

@@ -6,6 +6,7 @@ export type UseOptimisticReturn<State> = [
  * @name useOptimistic
  * @description - Hook that allows get optimistic value before its update
  * @category Async
+ * @usage medium
  *
  * @template State The type of the state
  * @param {State} state The value to be returned initially and whenever no action is pending

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

@@ -7,7 +7,7 @@ export interface UseOrientationValue {
     /** The current angle */
     angle: number;
     /** The current orientation type */
-    orientationType: OrientationType;
+    orientationType?: OrientationType;
 }
 export type OrientationLockType = 'any' | 'landscape-primary' | 'landscape-secondary' | 'landscape' | 'natural' | 'portrait-primary' | 'portrait-secondary' | 'portrait';
 export interface useOrientationReturn {
@@ -24,6 +24,7 @@ export interface useOrientationReturn {
  * @name useOrientation
  * @description - Hook that provides the current screen orientation
  * @category Sensors
+ * @usage low
  *
  * @browserapi screen.orientation https://developer.mozilla.org/en-US/docs/Web/API/Screen/orientation
  *

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

@@ -28,6 +28,7 @@ export interface UseOtpCredential {
  * @name useOtpCredential
  * @description - Hook that creates an otp credential
  * @category Browser
+ * @usage low
  *
  * @browserapi navigator.credentials https://developer.mozilla.org/en-US/docs/Web/API/Navigator/credentials
  *

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

@@ -2,6 +2,7 @@
  * @name usePageLeave
  * @description - Hook what calls given function when mouse leaves the page
  * @category Sensors
+ * @usage low
  *
  * @param {() => void} [callback] The callback function what calls then mouse leaves the page
  * @returns {boolean} A boolean which determines if the mouse left the page

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

@@ -78,6 +78,7 @@ export interface UsePaint {
  * @name usePaint
  * @description - Hook that allows you to draw in a specific area
  * @category Elements
+ * @usage low
  *
  * @overload
  * @param {HookTarget} target The target element to be painted

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

@@ -33,6 +33,7 @@ export interface UseParallax {
  * @name useParallax
  * @description - Hook to help create parallax effect
  * @category Sensors
+ * @usage low
  *
  * @overload
  * @param {HookTarget} target The target element for the parallax effect

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

@@ -7,6 +7,7 @@ export type UsePerformanceObserverOptions = PerformanceObserverInit & {
  * @name usePerformanceObserver
  * @description - Hook that allows you to observe performance entries
  * @category Sensors
+ * @usage low
  *
  * @browserapi PerformanceObserver https://developer.mozilla.org/en-US/docs/Web/API/PerformanceObserver
  *

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

@@ -18,6 +18,7 @@ export interface UsePermissionReturn {
  *  @name usePermission
  *  @description - Hook that gives you the state of permission
  *  @category Browser
+ *  @usage medium
  *
  *  @browserapi navigator.permissions https://developer.mozilla.org/en-US/docs/Web/API/Navigator/permissions
  *

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

@@ -30,6 +30,7 @@ export interface UsePictureInPicture {
  * @name usePictureInPicture
  * @description - Hook that provides Picture-in-Picture functionality for video elements
  * @category Browser
+ * @usage low
  *
  * @browserapi window.PictureInPicture https://developer.mozilla.org/en-US/docs/Web/API/Picture-in-Picture_API
  *

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

@@ -14,6 +14,7 @@ interface UsePointerLockReturn {
  * @name usePointerLock
  * @description - Hook that provides reactive pointer lock
  * @category Browser
+ * @usage low
  *
  * @browserapi pointerLockElement https://developer.mozilla.org/en-US/docs/Web/API/Document/pointerLockElement
  *

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

@@ -3,6 +3,7 @@ export type UsePostMessageReturn<Message> = (message: Message) => void;
  * @name usePostMessage
  * @description - Hook that allows you to receive messages from other origins
  * @category Browser
+ * @usage low
  *
  * @overload
  * @template Message The message data type

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

@@ -4,6 +4,7 @@ export type UsePreferredColorSchemeReturn = 'dark' | 'light' | 'no-preference';
  * @name usePreferredColorScheme
  * @description - Hook that returns user preferred color scheme
  * @category User
+ * @usage medium
  *
  * @returns {UsePreferredColorSchemeReturn} String of preferred color scheme
  *

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

@@ -4,6 +4,7 @@ export type UsePreferredContrastReturn = 'custom' | 'less' | 'more' | 'no-prefer
  * @name usePreferredContrast
  * @description - Hook that returns the contrast preference
  * @category User
+ * @usage medium
  *
  * @returns {UsePreferredContrastReturn} The contrast preference
  *

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

@@ -2,6 +2,7 @@
  * @name usePreferredDark
  * @description - Hook that returns if the user prefers dark mode
  * @category User
+ * @usage medium
  *
  * @example
  * const isDark = usePreferredDark();

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

@@ -2,6 +2,7 @@
  * @name usePreferredLanguages
  * @description Hook that returns a browser preferred languages from navigator
  * @category User
+ * @usage medium
  *
  * @browserapi navigator.languages https://developer.mozilla.org/en-US/docs/Web/API/Navigator/languages
  *

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

@@ -4,6 +4,7 @@ export type UsePreferredReducedMotionReturn = 'no-preference' | 'reduce';
  * @name usePreferredReducedMotion
  * @description - Hook that returns the reduced motion preference
  * @category User
+ * @usage low
  *
  * @returns {UsePreferredReducedMotionReturn} The reduced motion preference
  *

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

@@ -5,6 +5,7 @@ export interface UsePreviousOptions<Value> {
  * @name usePrevious
  * @description - Hook that returns the previous value
  * @category Utilities
+ * @usage low
  *
  * @template Value The type of the value
  * @param {Value} value The value to get the previous value

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

@@ -29,6 +29,7 @@ export interface UseQueryReturn<Data> {
  * @name useQuery
  * @description - Hook that defines the logic when query data
  * @category Async
+ * @usage high
  *
  * @template Data The type of the data
  * @param {() => Promise<Data>} callback The callback function to be invoked

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

@@ -19,6 +19,7 @@ export interface UseQueueReturn<Value> {
  * @name useQueue
  * @description - Hook that manages a queue
  * @category State
+ * @usage medium
  *
  * @template Value The type of the value
  * @param {Value[]} [initialValue=[]] The initial value of the queue

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

@@ -23,6 +23,7 @@ export interface UseRafReturn {
  * @name useRaf
  * @description - Hook that defines the logic for raf callback
  * @category Browser
+ * @usage low
  *
  * @browserapi requestAnimationFrame https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame
  *

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

@@ -3,6 +3,9 @@ export type UseRafStateReturn<Value> = [Value, (value: Value) => void];
  * @name useRafState
  * @description - Hook that returns the value and a function to set the value
  * @category State
+ * @usage low
+ *
+ * @browserapi requestAnimationFrame https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame
  *
  * @template Value The type of the value
  * @param {Value} initialValue The initial value

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

@@ -7,6 +7,7 @@ export interface StateRef<Value> {
  * @name useRefState
  * @description - Hook that returns the state reference of the value
  * @category State
+ * @usage low
  *
  * @template Value The type of the value
  * @param {Value} [initialValue] The initial value

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

@@ -2,6 +2,7 @@
  * @name useRenderCount
  * @description - Hook returns count component render times
  * @category Debug
+ * @usage low
  *
  * @returns {number} A number which determines how many times component renders
  *

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

@@ -13,6 +13,7 @@ export interface UseRenderInfoReturn {
  * @name useRenderInfo
  * @description - Hook for getting information about component rerender
  * @category Debug
+ * @usage low
  *
  * @param {string} [name='Unknown'] Component name
  * @param {boolean} [log=true] Toggle logging

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

@@ -4,6 +4,7 @@ type UseRerenderReturn = () => void;
  * @name useRerender
  * @description - Hook that defines the logic to force rerender a component
  * @category Debug
+ * @usage medium
  *
  * @returns {UseRerenderReturn} The rerender function
  *