main 🧊 add target method

Author: debabin

packages/core/src/bundle/hooks/useClickOutside/useClickOutside.js

@@ -7,8 +7,7 @@ import { useRefState } from '../useRefState/useRefState';
  * @category Sensors
  *
  * @overload
- * @template Target The target element(s)
- * @param {Target} target The target element(s) to detect outside clicks for
+ * @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
  * @returns {void}
  *

packages/core/src/bundle/hooks/useCssVar/useCssVar.js

@@ -1,5 +1,5 @@
 import { useEffect, useState } from 'react';
-import { getElement } from '@/utils/helpers';
+import { getElement, isTarget } from '@/utils/helpers';
 import { useRefState } from '../useRefState/useRefState';
 /**
  * @name useCssVar
@@ -9,23 +9,22 @@ import { useRefState } from '../useRefState/useRefState';
  * @overload
  * @param {string} key The CSS variable key
  * @param {string} initialValue The initial value of the CSS variable
- * @returns {UseCssVarReturn} The object containing the value of the CSS variable
+ * @returns {UseCssVarReturn & { ref: StateRef<Element> }} The object containing the value of the CSS variable and ref
  *
  * @example
- * const { ref, value, set } = useCssVar('color', 'red');
+ * const { ref, value, set } = useCssVar('--color', 'red');
  *
  * @overload
- * @template Target The target element
- * @param {Target} target The target element
+ * @param {HookTarget} target The target element
  * @param {string} key The CSS variable key
  * @param {string} initialValue The initial value of the CSS variable
  * @returns {UseCssVarReturn} The object containing the value of the CSS variable
  *
  * @example
- * const { value, set } = useCssVar(ref, 'color', 'red');
+ * const { value, set } = useCssVar(ref, '--color', 'red');
  */
 export const useCssVar = ((...params) => {
-    const target = (typeof params[0] === 'object' ? params[0] : undefined);
+    const target = (isTarget(params[0]) ? params[0] : undefined);
     const key = (target ? params[1] : params[0]);
     const initialValue = (target ? params[2] : params[1]);
     const [value, setValue] = useState(initialValue ?? '');
@@ -67,8 +66,7 @@ export const useCssVar = ((...params) => {
             observer.disconnect();
         };
     }, [target, internalRef.state]);
-    return {
-        value,
-        set
-    };
+    if (target)
+        return { value, set };
+    return { ref: internalRef, value, set };
 });

packages/core/src/bundle/hooks/useDisplayMedia/useDisplayMedia.js

@@ -9,10 +9,9 @@ import { useRefState } from '../useRefState/useRefState';
  * @browserapi mediaDevices.getDisplayMedia https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getDisplayMedia
  *
  * @overload
- * @template Target The target video element
- * @param {Target} target The target video element to display the media stream
+ * @param {HookTarget} target The target video element to display the media stream
  * @param {boolean | MediaTrackConstraints} [options.audio] Whether to enable audio sharing
- * @param {boolean} [options.enabled=false] Whether to start immediately
+ * @param {boolean} [options.immediately=false] Whether to start immediately
  * @param {boolean | MediaTrackConstraints} [options.video] Whether to enable video sharing
  * @returns {UseDisplayMediaReturn} Object containing stream, sharing status and control methods
  *
@@ -22,7 +21,7 @@ import { useRefState } from '../useRefState/useRefState';
  * @overload
  * @template Target The target video element
  * @param {boolean | MediaTrackConstraints} [options.audio] Whether to enable audio sharing
- * @param {boolean} [options.enabled=false] Whether to start immediately
+ * @param {boolean} [options.immediately=false] Whether to start immediately
  * @param {boolean | MediaTrackConstraints} [options.video] Whether to enable video sharing
  * @returns {UseDisplayMediaReturn & { ref: StateRef<HTMLVideoElement> }} Object containing stream, sharing status, control methods and ref
  *
@@ -36,7 +35,7 @@ export const useDisplayMedia = ((...params) => {
         'getDisplayMedia' in navigator.mediaDevices;
     const target = (isTarget(params[0]) ? params[0] : undefined);
     const options = (params[1] ? params[1] : params[0]);
-    const enabled = options?.enabled ?? false;
+    const immediately = options?.immediately ?? false;
     const [sharing, setSharing] = useState(false);
     const streamRef = useRef(null);
     const internalRef = useRefState();
@@ -68,7 +67,7 @@ export const useDisplayMedia = ((...params) => {
         return displayMedia;
     };
     useEffect(() => {
-        if (!supported || !enabled)
+        if (!supported || !immediately)
             return;
         if (!target && !internalRef.state)
             return;

packages/core/src/bundle/hooks/useElementSize/useElementSize.js

@@ -1,5 +1,5 @@
 import { useState } from 'react';
-import { getElement, isTarget } from '@/utils/helpers';
+import { getElement } from '@/utils/helpers';
 import { useIsomorphicLayoutEffect } from '../useIsomorphicLayoutEffect/useIsomorphicLayoutEffect';
 import { useRefState } from '../useRefState/useRefState';
 /**
@@ -8,8 +8,7 @@ import { useRefState } from '../useRefState/useRefState';
  * @category Elements
  *
  * @overload
- * @template Target The target element type
- * @param {UseElementSizeTarget} target The target element to observe
+ * @param {HookTarget} target The target element to observe
  * @returns {UseElementSizeReturn} An object containing the current width and height of the element
  *
  * @example
@@ -22,7 +21,7 @@ import { useRefState } from '../useRefState/useRefState';
  * const { ref, value } = useElementSize();
  */
 export const useElementSize = ((...params) => {
-    const target = (isTarget(params[0]) ? params[0] : undefined);
+    const target = params[0];
     const [size, setSize] = useState({ width: 0, height: 0 });
     const internalRef = useRefState();
     useIsomorphicLayoutEffect(() => {

packages/core/src/bundle/hooks/useEventListener/useEventListener.js

@@ -1,5 +1,5 @@
 import { useEffect } from 'react';
-import { getElement } from '@/utils/helpers';
+import { getElement, isTarget } from '@/utils/helpers';
 import { useEvent } from '../useEvent/useEvent';
 import { useRefState } from '../useRefState/useRefState';
 /**
@@ -32,7 +32,7 @@ import { useRefState } from '../useRefState/useRefState';
  * @overload
  * @template Event Key of window event map
  * @template Target The target element
- * @param {Target} target The target element to attach the event listener to
+ * @param {HookTarget} target The target element to attach the event listener to
  * @param {Event | Event[]} event An array of event types to listen for
  * @param {(this: Target, event: HTMLElementEventMap[Event]) => void} handler The event handler function
  * @param {UseEventListenerOptions} [options] Options for the event listener
@@ -53,7 +53,7 @@ import { useRefState } from '../useRefState/useRefState';
  * const ref = useEventListener('click', () => console.log('click'));
  */
 export const useEventListener = ((...params) => {
-    const target = (params[1] instanceof Function ? undefined : params[0]);
+    const target = (isTarget(params[0]) ? params[0] : undefined);
     const event = (target ? params[1] : params[0]);
     const events = Array.isArray(event) ? event : [event];
     const listener = (target ? params[2] : params[1]);

packages/core/src/bundle/hooks/useFocus/useFocus.js

@@ -7,27 +7,33 @@ import { useRefState } from '../useRefState/useRefState';
  * @category Browser
  *
  * @overload
- * @template Target The target element
- * @param {Target} target The target element to focus
+ * @param {HookTarget} target The target element to focus
  * @param {boolean} [options.initialValue=false] The initial focus state of the target
- * @returns {UseFocusReturn} An object with a `focus` boolean state value
+ * @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
+ * @returns {UseFocusReturn} An object with focus state and methods
  *
  * @example
  * const { focus, blur, focused } = useFocus(ref);
  *
  * @overload
+ * @template Target The target element
  * @param {boolean} [options.initialValue=false] The initial focus state of the target
- * @returns {UseFocusReturn} An object with a `focus` boolean state value
+ * @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
+ * @returns {UseFocusReturn & { ref: StateRef<Target> }} An object with focus state, methods and ref
  *
  * @example
  * const { ref, focus, blur, focused } = useFocus();
  */
 export const useFocus = ((...params) => {
-    const target = isTarget(params[0]) ? params[0] : undefined;
+    const target = (isTarget(params[0]) ? params[0] : undefined);
     const options = (target ? params[1] : params[0]) ?? {};
     const initialValue = options.initialValue ?? false;
     const [focused, setFocused] = useState(initialValue);
     const internalRef = useRefState();
+    const internalOptionsRef = useRef(options);
+    internalOptionsRef.current = options;
     const elementRef = useRef(null);
     const focus = () => elementRef.current?.focus();
     const blur = () => elementRef.current?.blur();
@@ -39,10 +45,14 @@ export const useFocus = ((...params) => {
             return;
         elementRef.current = element;
         const onFocus = (event) => {
+            internalOptionsRef.current?.onFocus?.(event);
             if (!focus || event.target.matches?.(':focus-visible'))
                 setFocused(true);
         };
-        const onBlur = () => setFocused(false);
+        const onBlur = (event) => {
+            internalOptionsRef.current?.onBlur?.(event);
+            setFocused(false);
+        };
         if (initialValue)
             element.focus();
         element.addEventListener('focus', onFocus);

packages/core/src/bundle/hooks/useFullscreen/useFullscreen.js

@@ -8,8 +8,7 @@ import { useRefState } from '../useRefState/useRefState';
  * @category Browser
  *
  * @overload
- * @template Target The target element for fullscreen
- * @param {Target} target The target element for fullscreen
+ * @param {HookTarget} target The target element for fullscreen
  * @param {boolean} [options.initialValue=false] initial value of fullscreen
  * @param {() => void} [options.onEnter] on enter fullscreen
  * @param {() => void} [options.onExit] on exit fullscreen

packages/core/src/bundle/hooks/useHotkeys/useHotkeys.js

@@ -1,5 +1,6 @@
 import { useEffect, useRef } from 'react';
-import { getElement } from '@/utils/helpers';
+import { getElement, isTarget } from '@/utils/helpers';
+import { useEvent } from '../useEvent/useEvent';
 import { useRefState } from '../useRefState/useRefState';
 export const isHotkeyMatch = (hotkey, keys) => hotkey
     .toLowerCase()
@@ -14,8 +15,7 @@ export const isHotkeyMatch = (hotkey, keys) => hotkey
  * @category Sensors
  *
  * @overload
- * @template Target The target element
- * @param {Target} [target=window] The target element to attach the event listener to
+ * @param {HookTarget} [target=window] The target element to attach the event listener to
  * @param {string} hotkeys The hotkey to listen for
  * @param {(event: KeyboardEvent) => void} callback The callback function to execute when hotkey is pressed
  * @param {Record<string, string>} [options.alias] Alias map for hotkeys
@@ -41,52 +41,47 @@ export const isHotkeyMatch = (hotkey, keys) => hotkey
  * const ref = useHotkeys('ctrl+a, ctrl+b', () => console.log('hotkey pressed'));
  */
 export const useHotkeys = ((...params) => {
-    const target = params[0] instanceof Element ||
-        (params[0] && typeof params[0] === 'object' && 'current' in params[0])
-        ? params[0]
-        : undefined;
+    const target = (isTarget(params[0]) ? params[0] : undefined);
     const hotkeys = (target ? params[1] : params[0]);
     const callback = (target ? params[2] : params[1]);
     const options = (target ? params[3] : params[2]);
     const internalRef = useRefState(window);
     const keysRef = useRef([]);
-    const callbackRef = useRef(callback);
-    callbackRef.current = callback;
     const enabled = options?.enabled ?? true;
+    const onKeyDown = useEvent((event) => {
+        if (!enabled)
+            return;
+        if (keysRef.current.some(({ code }) => code === event.code))
+            return;
+        const alias = options?.alias?.[event.key] ?? event.code;
+        const updatedKeys = [...keysRef.current, { key: event.key, code: event.code, alias }];
+        keysRef.current = updatedKeys;
+        const hotkeysList = hotkeys.split(',').map((h) => h.trim());
+        const isMatch = hotkeysList.some((hotkey) => isHotkeyMatch(hotkey, updatedKeys));
+        if (!isMatch)
+            return;
+        event.preventDefault();
+        callback(event);
+    });
+    const onKeyUp = useEvent((event) => {
+        if (!enabled)
+            return;
+        keysRef.current = keysRef.current.filter(({ code }) => code !== event.code);
+    });
     useEffect(() => {
         keysRef.current = [];
         if (!target && !internalRef.state && !enabled)
             return;
         const element = (target ? getElement(target) : internalRef.current);
         if (!element)
             return;
-        const onKeyDown = (event) => {
-            if (!enabled)
-                return;
-            if (keysRef.current.some(({ code }) => code === event.code))
-                return;
-            const alias = options?.alias?.[event.key] ?? event.code;
-            const updatedKeys = [...keysRef.current, { key: event.key, code: event.code, alias }];
-            keysRef.current = updatedKeys;
-            const hotkeysList = hotkeys.split(',').map((h) => h.trim());
-            const isMatch = hotkeysList.some((hotkey) => isHotkeyMatch(hotkey, updatedKeys));
-            if (!isMatch)
-                return;
-            event.preventDefault();
-            callbackRef.current(event);
-        };
-        const onKeyUp = (event) => {
-            if (!enabled)
-                return;
-            keysRef.current = keysRef.current.filter(({ code }) => code !== event.code);
-        };
         element.addEventListener('keydown', onKeyDown);
         element.addEventListener('keyup', onKeyUp);
         return () => {
             element.removeEventListener('keydown', onKeyDown);
             element.removeEventListener('keyup', onKeyUp);
         };
-    }, [target, internalRef.state, enabled, hotkeys]);
+    }, [target, internalRef.state, enabled, hotkeys, onKeyDown, onKeyUp]);
     if (target)
         return;
     return internalRef;

packages/core/src/bundle/hooks/useHover/useHover.js

@@ -7,17 +7,15 @@ import { useRefState } from '../useRefState/useRefState';
  * @category Sensors
  *
  * @overload
- * @template Target The target element
- * @param {Target} target The target element to be hovered
+ * @param {HookTarget} target The target element to be hovered
  * @param {(event: Event) => void} [callback] The callback function to be invoked on mouse enter
  * @returns {boolean} The state of the hover
  *
  * @example
  * const hovering = useHover(ref, () => console.log('callback'));
  *
  * @overload
- * @template Target The target element
- * @param {Target} target The target element to be hovered
+ * @param {HookTarget} target The target element to be hovered
  * @param {(event: Event) => void} [options.onEntry] The callback function to be invoked on mouse enter
  * @param {(event: Event) => void} [options.onLeave] The callback function to be invoked on mouse leave
  * @returns {boolean} The state of the hover

packages/core/src/bundle/hooks/useInfiniteScroll/useInfiniteScroll.js

@@ -18,8 +18,7 @@ import { useRefState } from '../useRefState/useRefState';
  * const { ref, loading } = useInfiniteScroll(() => console.log('infinite scroll'));
  *
  * @overload
- * @template Target The target element
- * @param {Target} target The target element to detect infinite scroll for
+ * @param {HookTarget} target The target element to detect infinite scroll for
  * @param {(event: Event) => void} callback The callback to execute when a click outside the target is detected
  * @param {number} [options.distance=10] The distance in pixels to trigger the callback
  * @param {string} [options.direction='bottom'] The direction to trigger the callback

packages/core/src/bundle/hooks/useIntersectionObserver/useIntersectionObserver.js

@@ -7,11 +7,10 @@ import { useRefState } from '../useRefState/useRefState';
  * @category Browser
  *
  * @overload
- * @template Target The target element
- * @param {Target} target The target element to detect intersection
+ * @param {HookTarget} target The target element to detect intersection
  * @param {boolean} [options.enabled=true] The IntersectionObserver options
  * @param {((entries: IntersectionObserverEntry[], observer: IntersectionObserver) => void) | undefined} [options.onChange] The callback to execute when intersection is detected
- * @param {IntersectionObserverInit['root'] | RefObject<Element | null | undefined>} [options.root] The root element to observe
+ * @param {HookTarget} [options.root] The root element to observe
  * @returns {UseIntersectionObserverReturn} An object containing the state and the supported status
  *
  * @example
@@ -21,7 +20,7 @@ import { useRefState } from '../useRefState/useRefState';
  * @template Target The target element
  * @param {boolean} [options.enabled=true] The IntersectionObserver options
  * @param {((entries: IntersectionObserverEntry[], observer: IntersectionObserver) => void) | undefined} [options.onChange] The callback to execute when intersection is detected
- * @param {IntersectionObserverInit['root'] | RefObject<Element | null | undefined>} [options.root] The root element to observe
+ * @param {HookTarget} [options.root] The root element to observe
  * @returns {UseIntersectionObserverReturn & { ref: StateRef<Target> }} A React ref to attach to the target element
  *
  * @example
@@ -46,7 +45,7 @@ export const useIntersectionObserver = ((...params) => {
             internalOnChangeRef.current?.(entry);
         }, {
             ...options,
-            root: options?.root ? getElement(options?.root) : document
+            root: options?.root ? getElement(options.root) : document
         });
         observer.observe(element);
         return () => {