main 🧊 add debounce throttle effect, add use element visibility

Author: debabin

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

@@ -5,6 +5,7 @@ export * from './useDevicePixelRatio/useDevicePixelRatio';
 export * from './useDocumentEvent/useDocumentEvent';
 export * from './useDocumentVisibility/useDocumentVisibility';
 export * from './useElementSize/useElementSize';
+export * from './useElementVisibility/useElementVisibility';
 export * from './useEventListener/useEventListener';
 export * from './useHotkeys/useHotkeys';
 export * from './useIdle/useIdle';

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

@@ -0,0 +1,41 @@
+import { useEffect, useRef } from 'react';
+/**
+ * @name useDebounceEffect
+ * @description – Hook that runs an effect after a delay when dependencies change
+ * @category Utilities
+ * @usage high
+ *
+ * @param {EffectCallback} effect The effect callback to run
+ * @param {number} delay The delay in milliseconds
+ * @param {DependencyList} deps The dependencies list for the effect
+ *
+ * @example
+ * useDebounceEffect(() => console.log('effect'), 500, [value]);
+ */
+export const useDebounceEffect = (effect, delay, deps) => {
+  const mountedRef = useRef(true);
+  const timeoutRef = useRef(null);
+  const cleanupRef = useRef(undefined);
+  const effectRef = useRef(effect);
+  const delayRef = useRef(delay);
+  effectRef.current = effect;
+  delayRef.current = delay;
+  useEffect(() => {
+    if (mountedRef.current) {
+      mountedRef.current = false;
+      return;
+    }
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+    timeoutRef.current = setTimeout(() => {
+      cleanupRef.current = effectRef.current();
+    }, delayRef.current);
+    return () => {
+      if (timeoutRef.current) clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+      if (typeof cleanupRef.current === 'function') cleanupRef.current();
+    };
+  }, deps);
+};

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

@@ -13,18 +13,18 @@ import { useIsomorphicLayoutEffect } from '../useIsomorphicLayoutEffect/useIsomo
  * useDidUpdate(() => console.log("effect runs on updates"), deps);
  */
 export const useDidUpdate = (effect, deps) => {
-  const mounted = useRef(false);
+  const mountedRef = useRef(false);
   useIsomorphicLayoutEffect(
     () => () => {
-      mounted.current = false;
+      mountedRef.current = false;
     },
     []
   );
   useIsomorphicLayoutEffect(() => {
-    if (mounted.current) {
+    if (mountedRef.current) {
       return effect();
     }
-    mounted.current = true;
+    mountedRef.current = true;
     return undefined;
   }, deps);
 };

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

@@ -0,0 +1,95 @@
+import { useEffect, useRef, useState } from 'react';
+import { isTarget } from '@/utils/helpers';
+import { useRefState } from '../useRefState/useRefState';
+/**
+ * @name useElementVisibility
+ * @description – Hook that tracks element visibility using IntersectionObserver
+ * @category Sensors
+ * @usage medium
+ *
+ * @browserapi IntersectionObserver https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver
+ *
+ * @overload
+ * @template Target The target element type
+ * @param {UseElementVisibilityOptions} [options] The IntersectionObserver options
+ * @returns {UseElementVisibilityReturn & { ref: StateRef<Target> }} An object containing the visibility state and a ref to attach to the target element
+ *
+ * @example
+ * const { ref, entry, inView } = useElementVisibility();
+ *
+ * @overload
+ * @param {HookTarget} target The target element to detect visibility
+ * @param {UseElementVisibilityOptions} [options] The IntersectionObserver options
+ * @returns {UseElementVisibilityReturn} An object containing the visibility state
+ *
+ * @example
+ * const { entry, inView } = useElementVisibility(ref);
+ *
+ * @overload
+ * @template Target The target element type
+ * @param {((entry: IntersectionObserverEntry, observer: IntersectionObserver) => void)} callback The callback to execute when visibility changes
+ * @returns {UseElementVisibilityReturn & { ref: StateRef<Target> }} An object containing the visibility state and a ref to attach to the target element
+ *
+ * @example
+ * const { ref, entry, inView } = useElementVisibility((entry) => console.log('visible:', entry.isIntersecting));
+ *
+ * @overload
+ * @param {HookTarget} target The target element to detect visibility
+ * @param {((entry: IntersectionObserverEntry, observer: IntersectionObserver) => void)} callback The callback to execute when visibility changes
+ * @returns {UseElementVisibilityReturn} An object containing the visibility state
+ *
+ * @example
+ * const { entry, inView } = useElementVisibility(ref, (entry) => console.log('visible:', entry.isIntersecting));
+ */
+export const useElementVisibility = (...params) => {
+  const target = isTarget(params[0]) ? params[0] : undefined;
+  const options = target
+    ? typeof params[1] === 'object'
+      ? params[1]
+      : { onChange: params[1] }
+    : typeof params[0] === 'object'
+      ? params[0]
+      : { onChange: params[0] };
+  const callback = options?.onChange;
+  const enabled = options?.enabled ?? true;
+  const [entry, setEntry] = useState();
+  const inView = entry?.isIntersecting ?? false;
+  const internalRef = useRefState();
+  const internalCallbackRef = useRef(callback);
+  internalCallbackRef.current = callback;
+  useEffect(() => {
+    if (!enabled || (!target && !internalRef.state)) return;
+    const element = target ? isTarget.getElement(target) : internalRef.current;
+    if (!element) return;
+    const observer = new IntersectionObserver(
+      (entries) => {
+        const firstEntry = entries[0];
+        if (firstEntry) {
+          setEntry(firstEntry);
+          internalCallbackRef.current?.(firstEntry, observer);
+        }
+      },
+      {
+        ...options,
+        root: options?.root ? isTarget.getElement(options.root) : document
+      }
+    );
+    observer.observe(element);
+    return () => {
+      observer.disconnect();
+    };
+  }, [
+    target && isTarget.getRawElement(target),
+    internalRef.state,
+    options?.rootMargin,
+    options?.threshold,
+    options?.root,
+    enabled
+  ]);
+  if (target) return { entry, inView };
+  return {
+    entry,
+    inView,
+    ref: internalRef
+  };
+};

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

@@ -0,0 +1,44 @@
+import { useEffect, useRef } from 'react';
+/**
+ * @name useThrottleEffect
+ * @description – Hook that runs an effect at most once per delay period when dependencies change
+ * @category Utilities
+ * @usage medium
+ *
+ * @param {EffectCallback} effect The effect callback to run
+ * @param {number} delay The delay in milliseconds
+ * @param {DependencyList} deps The dependencies list for the effect
+ *
+ * @example
+ * useThrottleEffect(() => console.log('effect'), 500, [value]);
+ */
+export const useThrottleEffect = (effect, delay, deps) => {
+  const mountedRef = useRef(true);
+  const cleanupRef = useRef(undefined);
+  const timeoutRef = useRef(null);
+  const isCalledRef = useRef(false);
+  const effectRef = useRef(effect);
+  const delayRef = useRef(delay);
+  effectRef.current = effect;
+  delayRef.current = delay;
+  useEffect(() => {
+    if (mountedRef.current) {
+      mountedRef.current = false;
+      return;
+    }
+    if (isCalledRef.current) return;
+    cleanupRef.current = effectRef.current();
+    isCalledRef.current = true;
+    setTimeout(() => {
+      isCalledRef.current = false;
+      timeoutRef.current = setTimeout(() => {
+        cleanupRef.current = effectRef.current();
+      }, delayRef.current);
+    }, delayRef.current);
+    return () => {
+      if (timeoutRef.current) clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+      if (typeof cleanupRef.current === 'function') cleanupRef.current();
+    };
+  }, deps);
+};

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

@@ -3,12 +3,14 @@ export * from './useBatchedCallback/useBatchedCallback';
 export * from './useConst/useConst';
 // timing
 export * from './useDebounceCallback/useDebounceCallback';
+export * from './useDebounceEffect/useDebounceEffect';
 export * from './useDebounceState/useDebounceState';
 export * from './useDebounceValue/useDebounceValue';
 export * from './useEvent/useEvent';
 export * from './useLastChanged/useLastChanged';
 export * from './useLatest/useLatest';
 export * from './usePrevious/usePrevious';
 export * from './useThrottleCallback/useThrottleCallback';
+export * from './useThrottleEffect/useThrottleEffect';
 export * from './useThrottleState/useThrottleState';
 export * from './useThrottleValue/useThrottleValue';

packages/core/src/hooks/sensors.ts

@@ -5,6 +5,7 @@ export * from './useDevicePixelRatio/useDevicePixelRatio';
 export * from './useDocumentEvent/useDocumentEvent';
 export * from './useDocumentVisibility/useDocumentVisibility';
 export * from './useElementSize/useElementSize';
+export * from './useElementVisibility/useElementVisibility';
 export * from './useEventListener/useEventListener';
 export * from './useHotkeys/useHotkeys';
 export * from './useIdle/useIdle';

packages/core/src/hooks/useDebounceEffect/useDebounceEffect.demo.tsx

@@ -0,0 +1,45 @@
+import { useCounter, useDebounceEffect } from '@siberiacancode/reactuse';
+
+const Demo = () => {
+  const counter = useCounter();
+  const debounceCounter = useCounter();
+  const effectCounter = useCounter();
+
+  useDebounceEffect(
+    () => {
+      debounceCounter.inc();
+      effectCounter.inc();
+    },
+    500,
+    [counter.value]
+  );
+
+  return (
+    <>
+      <div className='flex flex-col gap-1'>
+        <div className='text-sm'>
+          Current count: <code>{counter.value}</code>
+        </div>
+        <div className='text-sm'>
+          Debounced count: <code>{debounceCounter.value}</code>
+        </div>
+        <div className='text-sm'>
+          Effect runs: <code>{effectCounter.value}</code>
+        </div>
+      </div>
+
+      <div className='mt-4 flex flex-wrap'>
+        <button type='button' onClick={() => counter.inc()}>
+          Increment
+        </button>
+        <button type='button' onClick={() => counter.dec()}>
+          Decrement
+        </button>
+      </div>
+
+      <div className='mt-4 text-xs'>Click buttons rapidly to see the debounce effect.</div>
+    </>
+  );
+};
+
+export default Demo;

packages/core/src/hooks/useDebounceEffect/useDebounceEffect.test.ts

@@ -0,0 +1,64 @@
+import { act, renderHook } from '@testing-library/react';
+import { vi } from 'vitest';
+
+import { renderHookServer } from '@/tests';
+
+import { useDebounceEffect } from './useDebounceEffect';
+
+beforeEach(vi.useFakeTimers);
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.restoreAllMocks();
+});
+
+it('Should use debounce effect', () => {
+  const effect = vi.fn();
+  renderHook(() => useDebounceEffect(effect, 100, []));
+
+  act(() => vi.advanceTimersByTime(100));
+
+  expect(effect).not.toHaveBeenCalled();
+});
+
+it('Should use debounce effect on server side', () => {
+  const effect = vi.fn();
+  renderHookServer(() => useDebounceEffect(effect, 100, []));
+
+  expect(effect).not.toHaveBeenCalled();
+});
+
+it('Should debounce effect execution', () => {
+  const effect = vi.fn();
+
+  const { rerender } = renderHook(({ value }) => useDebounceEffect(effect, 100, [value]), {
+    initialProps: { value: 'initial value' }
+  });
+
+  expect(effect).not.toHaveBeenCalled();
+
+  rerender({ value: 'new value' });
+
+  act(() => vi.advanceTimersByTime(100));
+
+  expect(effect).toHaveBeenCalledOnce();
+});
+
+it('Should cleanup on unmount', () => {
+  const cleanup = vi.fn();
+  const effect = vi.fn(() => cleanup);
+
+  const { unmount, rerender } = renderHook((value) => useDebounceEffect(effect, 100, [value]), {
+    initialProps: 'initial value'
+  });
+
+  expect(effect).not.toHaveBeenCalled();
+
+  rerender('new value');
+
+  act(() => vi.advanceTimersByTime(100));
+
+  unmount();
+
+  expect(cleanup).toHaveBeenCalledOnce();
+});

packages/core/src/hooks/useDebounceEffect/useDebounceEffect.ts

@@ -0,0 +1,49 @@
+import type { DependencyList, EffectCallback } from 'react';
+
+import { useEffect, useRef } from 'react';
+
+/**
+ * @name useDebounceEffect
+ * @description – Hook that runs an effect after a delay when dependencies change
+ * @category Utilities
+ * @usage high
+ *
+ * @param {EffectCallback} effect The effect callback to run
+ * @param {number} delay The delay in milliseconds
+ * @param {DependencyList} deps The dependencies list for the effect
+ *
+ * @example
+ * useDebounceEffect(() => console.log('effect'), 500, [value]);
+ */
+export const useDebounceEffect = (effect: EffectCallback, delay: number, deps?: DependencyList) => {
+  const mountedRef = useRef(true);
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const cleanupRef = useRef<ReturnType<EffectCallback>>(undefined);
+  const effectRef = useRef(effect);
+  const delayRef = useRef(delay);
+
+  effectRef.current = effect;
+  delayRef.current = delay;
+
+  useEffect(() => {
+    if (mountedRef.current) {
+      mountedRef.current = false;
+      return;
+    }
+
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+
+    timeoutRef.current = setTimeout(() => {
+      cleanupRef.current = effectRef.current();
+    }, delayRef.current);
+
+    return () => {
+      if (timeoutRef.current) clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+      if (typeof cleanupRef.current === 'function') cleanupRef.current();
+    };
+  }, deps);
+};