react-simplikit 0.0.48 → 0.0.49

package/esm/hooks/useDebounce/index.js

@@ -8,9 +8,12 @@ import { useMemo } from "react";
 import { useCallback, useEffect, useRef } from "react";
 function usePreservedCallback(callback) {
   const callbackRef = useRef(callback);
-  useEffect(() => {
-    callbackRef.current = callback;
-  }, [callback]);
+  useEffect(
+    function syncCallbackRef() {
+      callbackRef.current = callback;
+    },
+    [callback]
+  );
   return useCallback((...args) => {
     return callbackRef.current(...args);
   }, []);
@@ -86,11 +89,14 @@ function useDebounce(callback, wait, options = {}) {
   const debounced = useMemo(() => {
     return debounce(preservedCallback, wait, { edges });
   }, [preservedCallback, wait, edges]);
-  useEffect2(() => {
-    return () => {
-      debounced.cancel();
-    };
-  }, [debounced]);
+  useEffect2(
+    function cancelDebouncedOnUnmount() {
+      return () => {
+        debounced.cancel();
+      };
+    },
+    [debounced]
+  );
   return debounced;
 }
 export {

package/esm/hooks/useDebouncedCallback/index.js

@@ -60,9 +60,12 @@ function debounce(func, debounceMs, { edges = ["leading", "trailing"] } = {}) {
 import { useCallback, useEffect, useRef } from "react";
 function usePreservedCallback(callback) {
   const callbackRef = useRef(callback);
-  useEffect(() => {
-    callbackRef.current = callback;
-  }, [callback]);
+  useEffect(
+    function syncCallbackRef() {
+      callbackRef.current = callback;
+    },
+    [callback]
+  );
   return useCallback((...args) => {
     return callbackRef.current(...args);
   }, []);
@@ -78,7 +81,7 @@ function useDebouncedCallback({
   const handleChange = usePreservedCallback(onChange);
   const ref = useRef2({ value: false, clearPreviousDebounce: () => {
   } });
-  useEffect2(() => {
+  useEffect2(function clearDebouncedOnUnmount() {
     const current = ref.current;
     return () => {
       current.clearPreviousDebounce();

package/esm/hooks/useDoubleClick/index.js

@@ -7,9 +7,12 @@ import { useCallback as useCallback2, useEffect as useEffect2, useRef as useRef2
 import { useCallback, useEffect, useRef } from "react";
 function usePreservedCallback(callback) {
   const callbackRef = useRef(callback);
-  useEffect(() => {
-    callbackRef.current = callback;
-  }, [callback]);
+  useEffect(
+    function syncCallbackRef() {
+      callbackRef.current = callback;
+    },
+    [callback]
+  );
   return useCallback((...args) => {
     return callbackRef.current(...args);
   }, []);

package/esm/hooks/useImpressionRef/index.js

@@ -63,9 +63,12 @@ function debounce(func, debounceMs, { edges = ["leading", "trailing"] } = {}) {
 import { useCallback, useEffect, useRef } from "react";
 function usePreservedCallback(callback) {
   const callbackRef = useRef(callback);
-  useEffect(() => {
-    callbackRef.current = callback;
-  }, [callback]);
+  useEffect(
+    function syncCallbackRef() {
+      callbackRef.current = callback;
+    },
+    [callback]
+  );
   return useCallback((...args) => {
     return callbackRef.current(...args);
   }, []);
@@ -81,7 +84,7 @@ function useDebouncedCallback({
   const handleChange = usePreservedCallback(onChange);
   const ref = useRef2({ value: false, clearPreviousDebounce: () => {
   } });
-  useEffect2(() => {
+  useEffect2(function clearDebouncedOnUnmount() {
     const current = ref.current;
     return () => {
       current.clearPreviousDebounce();

package/esm/hooks/useIntersectionObserver/index.js

@@ -7,9 +7,12 @@ import { useMemo } from "react";
 import { useCallback, useEffect, useRef } from "react";
 function usePreservedCallback(callback) {
   const callbackRef = useRef(callback);
-  useEffect(() => {
-    callbackRef.current = callback;
-  }, [callback]);
+  useEffect(
+    function syncCallbackRef() {
+      callbackRef.current = callback;
+    },
+    [callback]
+  );
   return useCallback((...args) => {
     return callbackRef.current(...args);
   }, []);

package/esm/hooks/useInterval/index.js

@@ -7,9 +7,12 @@ import { useEffect as useEffect2 } from "react";
 import { useCallback, useEffect, useRef } from "react";
 function usePreservedCallback(callback) {
   const callbackRef = useRef(callback);
-  useEffect(() => {
-    callbackRef.current = callback;
-  }, [callback]);
+  useEffect(
+    function syncCallbackRef() {
+      callbackRef.current = callback;
+    },
+    [callback]
+  );
   return useCallback((...args) => {
     return callbackRef.current(...args);
   }, []);
@@ -21,18 +24,24 @@ function useInterval(callback, options) {
   const immediate = typeof options === "number" ? false : options.immediate;
   const enabled = typeof options === "number" ? true : options.enabled ?? true;
   const preservedCallback = usePreservedCallback(callback);
-  useEffect2(() => {
-    if (immediate === true && enabled) {
-      preservedCallback();
-    }
-  }, [immediate, preservedCallback, enabled]);
-  useEffect2(() => {
-    if (!enabled) {
-      return;
-    }
-    const id = window.setInterval(preservedCallback, delay);
-    return () => window.clearInterval(id);
-  }, [delay, preservedCallback, enabled]);
+  useEffect2(
+    function runImmediateCallback() {
+      if (immediate === true && enabled) {
+        preservedCallback();
+      }
+    },
+    [immediate, preservedCallback, enabled]
+  );
+  useEffect2(
+    function startInterval() {
+      if (!enabled) {
+        return;
+      }
+      const id = setInterval(preservedCallback, delay);
+      return () => clearInterval(id);
+    },
+    [delay, preservedCallback, enabled]
+  );
 }
 export {
   useInterval

package/esm/hooks/useIsClient/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @description
+ * `useIsClient` is a React hook that returns `true` only in the client-side environment.
+ * It is primarily used to differentiate between client-side and server-side rendering (SSR).
+ * The state is set to `true` only after the component is mounted in the client-side environment.
+ *
+ * @returns {boolean} Returns `true` in a client-side environment, and `false` otherwise.
+ *
+ * @example
+ * function ClientSideContent() {
+ *   const isClient = useIsClient();
+ *
+ *   if (!isClient) {
+ *     return <div>Loading...</div>; // Rendered on the server side
+ *   }
+ *
+ *   return <div>Client-side rendered content</div>; // Rendered on the client side
+ * }
+ *
+ * @example
+ * function ClientOnlyMap() {
+ *   const isClient = useIsClient();
+ *
+ *   if (!isClient) return null;
+ *
+ *   return <div id="map" />;
+ * }
+ *
+ * @example
+ * function ClientTheme() {
+ *   const isClient = useIsClient();
+ *
+ *   const theme = isClient ? localStorage.getItem('theme') : 'light';
+ *
+ *   return <div>Current theme: {theme}</div>;
+ * }
+ */
+declare function useIsClient(): boolean;
+
+export { useIsClient };

package/esm/hooks/useIsClient/index.js

@@ -0,0 +1,14 @@
+"use client";
+
+// src/hooks/useIsClient/useIsClient.ts
+import { useEffect, useState } from "react";
+function useIsClient() {
+  const [isClient, setIsClient] = useState(false);
+  useEffect(function syncClientState() {
+    setIsClient(true);
+  }, []);
+  return isClient;
+}
+export {
+  useIsClient
+};

package/esm/hooks/useList/index.d.ts

@@ -0,0 +1,50 @@
+type ListActions<T> = {
+    push: (value: T) => void;
+    insertAt: (index: number, value: T) => void;
+    updateAt: (index: number, value: T) => void;
+    removeAt: (index: number) => void;
+    setAll: (values: T[]) => void;
+    reset: () => void;
+};
+type UseListReturn<T> = [ReadonlyArray<T>, ListActions<T>];
+/**
+ * @description
+ * A React hook that manages an array as state.
+ * Provides efficient state management and stable action functions.
+ *
+ * @param {T[]} initialState - Initial array state
+ *
+ * @returns {UseListReturn<T>} A tuple containing the array state and actions to manipulate it
+ * - `push` - Appends a value to the end of the list
+ * - `insertAt` - Inserts a value at the specified index
+ * - `updateAt` - Updates the value at the specified index
+ * - `removeAt` - Removes the value at the specified index
+ * - `setAll` - Replaces the entire list with a new array
+ * - `reset` - Resets the list to its initial state
+ *
+ * @example
+ * ```tsx
+ * const [list, actions] = useList<string>(['apple', 'banana']);
+ *
+ * // Add an item
+ * actions.push('cherry');
+ *
+ * // Insert at index
+ * actions.insertAt(1, 'grape');
+ *
+ * // Update at index
+ * actions.updateAt(0, 'orange');
+ *
+ * // Remove at index
+ * actions.removeAt(2);
+ *
+ * // Replace all
+ * actions.setAll(['kiwi', 'mango']);
+ *
+ * // Reset to initial state
+ * actions.reset();
+ * ```
+ */
+declare function useList<T>(initialState?: T[]): UseListReturn<T>;
+
+export { useList };

package/esm/hooks/useList/index.js

@@ -0,0 +1,78 @@
+"use client";
+
+// src/hooks/useList/useList.ts
+import { useMemo as useMemo2, useState } from "react";
+
+// src/hooks/usePreservedCallback/usePreservedCallback.ts
+import { useCallback, useEffect, useRef } from "react";
+function usePreservedCallback(callback) {
+  const callbackRef = useRef(callback);
+  useEffect(
+    function syncCallbackRef() {
+      callbackRef.current = callback;
+    },
+    [callback]
+  );
+  return useCallback((...args) => {
+    return callbackRef.current(...args);
+  }, []);
+}
+
+// src/hooks/usePreservedReference/usePreservedReference.ts
+import { useMemo, useRef as useRef2 } from "react";
+function usePreservedReference(value, areValuesEqual = areDeeplyEqual) {
+  const ref = useRef2(value);
+  return useMemo(() => {
+    if (!areValuesEqual(ref.current, value)) {
+      ref.current = value;
+    }
+    return ref.current;
+  }, [areValuesEqual, value]);
+}
+function areDeeplyEqual(x, y) {
+  return JSON.stringify(x) === JSON.stringify(y);
+}
+
+// src/hooks/useList/useList.ts
+function useList(initialState = []) {
+  const [list, setList] = useState(initialState);
+  const preservedInitialState = usePreservedReference(initialState);
+  const push = usePreservedCallback((value) => {
+    setList((prev) => [...prev, value]);
+  });
+  const insertAt = usePreservedCallback((index, value) => {
+    setList((prev) => {
+      const next = [...prev];
+      next.splice(index, 0, value);
+      return next;
+    });
+  });
+  const updateAt = usePreservedCallback((index, value) => {
+    setList((prev) => {
+      const next = [...prev];
+      next[index] = value;
+      return next;
+    });
+  });
+  const removeAt = usePreservedCallback((index) => {
+    setList((prev) => {
+      const next = [...prev];
+      next.splice(index, 1);
+      return next;
+    });
+  });
+  const setAll = usePreservedCallback((values) => {
+    setList(values);
+  });
+  const reset = usePreservedCallback(() => {
+    setList(preservedInitialState);
+  });
+  const actions = useMemo2(
+    () => ({ push, insertAt, updateAt, removeAt, setAll, reset }),
+    [push, insertAt, updateAt, removeAt, setAll, reset]
+  );
+  return [list, actions];
+}
+export {
+  useList
+};

package/esm/hooks/useLoading/index.js

@@ -23,12 +23,15 @@ function useLoading() {
 }
 function useIsMountedRef() {
   const ref = useRef({ isMounted: true }).current;
-  useEffect(() => {
-    ref.isMounted = true;
-    return () => {
-      ref.isMounted = false;
-    };
-  }, [ref]);
+  useEffect(
+    function trackMountedState() {
+      ref.isMounted = true;
+      return () => {
+        ref.isMounted = false;
+      };
+    },
+    [ref]
+  );
   return ref;
 }
 export {

package/esm/hooks/useLongPress/index.js

@@ -7,9 +7,12 @@ import { useCallback as useCallback2, useRef as useRef2 } from "react";
 import { useCallback, useEffect, useRef } from "react";
 function usePreservedCallback(callback) {
   const callbackRef = useRef(callback);
-  useEffect(() => {
-    callbackRef.current = callback;
-  }, [callback]);
+  useEffect(
+    function syncCallbackRef() {
+      callbackRef.current = callback;
+    },
+    [callback]
+  );
   return useCallback((...args) => {
     return callbackRef.current(...args);
   }, []);

package/esm/hooks/useOutsideClickEffect/index.js

@@ -7,9 +7,12 @@ import { useEffect as useEffect2, useRef as useRef2 } from "react";
 import { useCallback, useEffect, useRef } from "react";
 function usePreservedCallback(callback) {
   const callbackRef = useRef(callback);
-  useEffect(() => {
-    callbackRef.current = callback;
-  }, [callback]);
+  useEffect(
+    function syncCallbackRef() {
+      callbackRef.current = callback;
+    },
+    [callback]
+  );
   return useCallback((...args) => {
     return callbackRef.current(...args);
   }, []);

package/esm/hooks/usePreservedCallback/index.js

@@ -4,9 +4,12 @@
 import { useCallback, useEffect, useRef } from "react";
 function usePreservedCallback(callback) {
   const callbackRef = useRef(callback);
-  useEffect(() => {
-    callbackRef.current = callback;
-  }, [callback]);
+  useEffect(
+    function syncCallbackRef() {
+      callbackRef.current = callback;
+    },
+    [callback]
+  );
   return useCallback((...args) => {
     return callbackRef.current(...args);
   }, []);

package/esm/hooks/useRefEffect/index.d.ts

@@ -6,10 +6,10 @@ type CleanupCallback = () => void;
  * `useRefEffect` is a React hook that helps you set a reference to a specific DOM element and execute a callback whenever the element changes.
  * This hook calls a cleanup function whenever the element changes to prevent memory leaks.
  *
- * @param {(element: Element) => CleanupCallback | void} callback - A callback function that is executed when the element is set. This function can return a cleanup function.
+ * @param {(element: RefElement) => CleanupCallback | void} callback - A callback function that is executed when the element is set. This function can return a cleanup function.
  * @param {DependencyList} deps - An array of dependencies that define when the callback should be re-executed. The `callback` is re-executed whenever the `deps` change.
  *
- * @returns {(element: Element | null) => void} A function to set the element. Pass this function to the `ref` attribute, and the `callback` will be called whenever the element changes.
+ * @returns {(element: RefElement | null) => void} A function to set the element. Pass this function to the `ref` attribute, and the `callback` will be called whenever the element changes.
  *
  * @example
  * import { useRefEffect } from 'react-simplikit';
@@ -26,6 +26,6 @@ type CleanupCallback = () => void;
  *   return <div ref={ref}>Basic Example</div>;
  * }
  */
-declare function useRefEffect<Element extends HTMLElement = HTMLElement>(callback: (element: Element) => CleanupCallback | void, deps: DependencyList): (element: Element | null) => void;
+declare function useRefEffect<RefElement extends HTMLElement = HTMLElement>(callback: (element: RefElement) => CleanupCallback | void, deps: DependencyList): (element: RefElement | null) => void;
 
 export { useRefEffect };

package/esm/hooks/useRefEffect/index.js

@@ -7,9 +7,12 @@ import { useCallback as useCallback2, useRef as useRef2 } from "react";
 import { useCallback, useEffect, useRef } from "react";
 function usePreservedCallback(callback) {
   const callbackRef = useRef(callback);
-  useEffect(() => {
-    callbackRef.current = callback;
-  }, [callback]);
+  useEffect(
+    function syncCallbackRef() {
+      callbackRef.current = callback;
+    },
+    [callback]
+  );
   return useCallback((...args) => {
     return callbackRef.current(...args);
   }, []);

package/esm/hooks/useSet/index.d.ts

@@ -0,0 +1,39 @@
+type SetOrValues<T> = Set<T> | T[];
+type SetActions<T> = {
+    add: (value: T) => void;
+    remove: (value: T) => void;
+    toggle: (value: T) => void;
+    setAll: (values: SetOrValues<T>) => void;
+    reset: () => void;
+};
+type UseSetReturn<T> = [Omit<Set<T>, 'add' | 'clear' | 'delete'>, SetActions<T>];
+/**
+ * @description
+ * A React hook that manages a Set as state.
+ * Provides efficient state management and stable action functions.
+ *
+ * @param {SetOrValues<T>} initialState - Initial Set state (Set object or array of values)
+ * @returns {UseSetReturn<T>} A tuple containing the Set state and actions to manipulate it
+ *
+ * @example
+ * ```tsx
+ * import { useSet } from 'react-simplikit';
+ *
+ * function TagSelector() {
+ *   const [selectedTags, { add, remove, toggle }] = useSet<string>(['react']);
+ *
+ *   return (
+ *     <div>
+ *       {['react', 'vue', 'svelte'].map(tag => (
+ *         <button key={tag} onClick={() => toggle(tag)}>
+ *           {selectedTags.has(tag) ? '✓' : ''} {tag}
+ *         </button>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useSet<T>(initialState?: SetOrValues<T>): UseSetReturn<T>;
+
+export { useSet };

package/esm/hooks/useSet/index.js

@@ -0,0 +1,79 @@
+"use client";
+
+// src/hooks/useSet/useSet.ts
+import { useMemo as useMemo2, useState } from "react";
+
+// src/hooks/usePreservedCallback/usePreservedCallback.ts
+import { useCallback, useEffect, useRef } from "react";
+function usePreservedCallback(callback) {
+  const callbackRef = useRef(callback);
+  useEffect(
+    function syncCallbackRef() {
+      callbackRef.current = callback;
+    },
+    [callback]
+  );
+  return useCallback((...args) => {
+    return callbackRef.current(...args);
+  }, []);
+}
+
+// src/hooks/usePreservedReference/usePreservedReference.ts
+import { useMemo, useRef as useRef2 } from "react";
+function usePreservedReference(value, areValuesEqual = areDeeplyEqual) {
+  const ref = useRef2(value);
+  return useMemo(() => {
+    if (!areValuesEqual(ref.current, value)) {
+      ref.current = value;
+    }
+    return ref.current;
+  }, [areValuesEqual, value]);
+}
+function areDeeplyEqual(x, y) {
+  return JSON.stringify(x) === JSON.stringify(y);
+}
+
+// src/hooks/useSet/useSet.ts
+function useSet(initialState = /* @__PURE__ */ new Set()) {
+  const [set, setSet] = useState(() => new Set(initialState));
+  const preservedInitialState = usePreservedReference(initialState);
+  const add = usePreservedCallback((value) => {
+    setSet((prev) => {
+      const nextSet = new Set(prev);
+      nextSet.add(value);
+      return nextSet;
+    });
+  });
+  const remove = usePreservedCallback((value) => {
+    setSet((prev) => {
+      const nextSet = new Set(prev);
+      nextSet.delete(value);
+      return nextSet;
+    });
+  });
+  const toggle = usePreservedCallback((value) => {
+    setSet((prev) => {
+      const nextSet = new Set(prev);
+      if (nextSet.has(value)) {
+        nextSet.delete(value);
+      } else {
+        nextSet.add(value);
+      }
+      return nextSet;
+    });
+  });
+  const setAll = usePreservedCallback((values) => {
+    setSet(() => new Set(values));
+  });
+  const reset = usePreservedCallback(() => {
+    setSet(() => new Set(preservedInitialState));
+  });
+  const actions = useMemo2(
+    () => ({ add, remove, toggle, setAll, reset }),
+    [add, remove, toggle, setAll, reset]
+  );
+  return [set, actions];
+}
+export {
+  useSet
+};

package/esm/hooks/useThrottle/index.js

@@ -7,9 +7,12 @@ import { useEffect as useEffect2, useMemo as useMemo2 } from "react";
 import { useCallback, useEffect, useRef } from "react";
 function usePreservedCallback(callback) {
   const callbackRef = useRef(callback);
-  useEffect(() => {
-    callbackRef.current = callback;
-  }, [callback]);
+  useEffect(
+    function syncCallbackRef() {
+      callbackRef.current = callback;
+    },
+    [callback]
+  );
   return useCallback((...args) => {
     return callbackRef.current(...args);
   }, []);

package/esm/hooks/useThrottledCallback/index.d.ts

@@ -0,0 +1,30 @@
+type ThrottleOptions = {
+    edges?: Array<'leading' | 'trailing'>;
+};
+/**
+ * @description
+ * `useThrottledCallback` is a React hook that returns a throttled version of the provided callback function.
+ * The throttled callback will only be invoked at most once per specified interval.
+ *
+ * @param {Object} options - The options object.
+ * @param {Function} options.onChange - The callback function to throttle.
+ * @param {number} options.timeThreshold - The number of milliseconds to throttle invocations to.
+ * @param {Array<'leading' | 'trailing'>} [options.edges=['leading', 'trailing']] - An optional array specifying whether the function should be invoked on the leading edge, trailing edge, or both.
+ *
+ * @returns {Function} A throttled function that limits invoking the callback.
+ *
+ * @example
+ * function ScrollTracker() {
+ *   const throttledScroll = useThrottledCallback({
+ *     onChange: (scrollY: number) => console.log(scrollY),
+ *     timeThreshold: 200,
+ *   });
+ *   return <div onScroll={(e) => throttledScroll(e.currentTarget.scrollTop)} />;
+ * }
+ */
+declare function useThrottledCallback({ onChange, timeThreshold, edges, }: ThrottleOptions & {
+    onChange: (newValue: boolean) => void;
+    timeThreshold: number;
+}): (nextValue: boolean) => void;
+
+export { useThrottledCallback };