react-simplikit 0.1.0 → 0.3.0

package/dist/{mobile/hooks → hooks}/useScrollDirection/useScrollDirection.cjs

@@ -1,7 +1,7 @@
 "use client";
 const require_isServer = require("../../utils/isServer/isServer.cjs");
 let react = require("react");
-//#region src/mobile/hooks/useScrollDirection/useScrollDirection.ts
+//#region src/hooks/useScrollDirection/useScrollDirection.ts
 /**
 * @description
 * `useScrollDirection` is a React hook that detects scroll direction.

package/dist/{mobile/hooks → hooks}/useScrollDirection/useScrollDirection.d.cts

@@ -1,5 +1,5 @@
 
-//#region src/mobile/hooks/useScrollDirection/useScrollDirection.d.ts
+//#region src/hooks/useScrollDirection/useScrollDirection.d.ts
 type ScrollDirection = 'up' | 'down' | null;
 type ScrollDirectionState = {
   /** Current scroll direction */

package/dist/{mobile/hooks → hooks}/useScrollDirection/useScrollDirection.d.mts

@@ -1,5 +1,5 @@
 
-//#region src/mobile/hooks/useScrollDirection/useScrollDirection.d.ts
+//#region src/hooks/useScrollDirection/useScrollDirection.d.ts
 type ScrollDirection = 'up' | 'down' | null;
 type ScrollDirectionState = {
   /** Current scroll direction */

package/dist/{mobile/hooks → hooks}/useScrollDirection/useScrollDirection.mjs

@@ -1,7 +1,7 @@
 "use client";
 import { isServer } from "../../utils/isServer/isServer.mjs";
 import { useCallback, useEffect, useRef, useState } from "react";
-//#region src/mobile/hooks/useScrollDirection/useScrollDirection.ts
+//#region src/hooks/useScrollDirection/useScrollDirection.ts
 /**
 * @description
 * `useScrollDirection` is a React hook that detects scroll direction.

package/dist/hooks/useSet/useSet.cjs

@@ -8,8 +8,17 @@ let react = require("react");
 * 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
+* @template T - The type of the values held in the set.
+*
+* @param {SetOrValues<T>} [initialState=new Set()] - Initial Set state (Set object or array of values).
+*
+* @returns {UseSetReturn<T>} A tuple containing the Set state and actions to manipulate it.
+* - [0] `Omit<Set<T>, 'add' | 'clear' | 'delete'>` - The current Set state with mutation methods hidden;
+* - [1].add `(value: T) => void` - Adds a value to the set;
+* - [1].remove `(value: T) => void` - Removes a value from the set;
+* - [1].toggle `(value: T) => void` - Adds the value if absent, removes it if present;
+* - [1].setAll `(values: Set<T> | T[]) => void` - Replaces all values in the set;
+* - [1].reset `() => void` - Resets the set to its initial state;
 *
 * @example
 * ```tsx

package/dist/hooks/useSet/useSet.d.cts

@@ -14,8 +14,17 @@ type UseSetReturn<T> = [Omit<Set<T>, 'add' | 'clear' | 'delete'>, SetActions<T>]
  * 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
+ * @template T - The type of the values held in the set.
+ *
+ * @param {SetOrValues<T>} [initialState=new Set()] - Initial Set state (Set object or array of values).
+ *
+ * @returns {UseSetReturn<T>} A tuple containing the Set state and actions to manipulate it.
+ * - [0] `Omit<Set<T>, 'add' | 'clear' | 'delete'>` - The current Set state with mutation methods hidden;
+ * - [1].add `(value: T) => void` - Adds a value to the set;
+ * - [1].remove `(value: T) => void` - Removes a value from the set;
+ * - [1].toggle `(value: T) => void` - Adds the value if absent, removes it if present;
+ * - [1].setAll `(values: Set<T> | T[]) => void` - Replaces all values in the set;
+ * - [1].reset `() => void` - Resets the set to its initial state;
  *
  * @example
  * ```tsx

package/dist/hooks/useSet/useSet.d.mts

@@ -14,8 +14,17 @@ type UseSetReturn<T> = [Omit<Set<T>, 'add' | 'clear' | 'delete'>, SetActions<T>]
  * 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
+ * @template T - The type of the values held in the set.
+ *
+ * @param {SetOrValues<T>} [initialState=new Set()] - Initial Set state (Set object or array of values).
+ *
+ * @returns {UseSetReturn<T>} A tuple containing the Set state and actions to manipulate it.
+ * - [0] `Omit<Set<T>, 'add' | 'clear' | 'delete'>` - The current Set state with mutation methods hidden;
+ * - [1].add `(value: T) => void` - Adds a value to the set;
+ * - [1].remove `(value: T) => void` - Removes a value from the set;
+ * - [1].toggle `(value: T) => void` - Adds the value if absent, removes it if present;
+ * - [1].setAll `(values: Set<T> | T[]) => void` - Replaces all values in the set;
+ * - [1].reset `() => void` - Resets the set to its initial state;
  *
  * @example
  * ```tsx

package/dist/hooks/useSet/useSet.mjs

@@ -8,8 +8,17 @@ import { useMemo, useState } from "react";
 * 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
+* @template T - The type of the values held in the set.
+*
+* @param {SetOrValues<T>} [initialState=new Set()] - Initial Set state (Set object or array of values).
+*
+* @returns {UseSetReturn<T>} A tuple containing the Set state and actions to manipulate it.
+* - [0] `Omit<Set<T>, 'add' | 'clear' | 'delete'>` - The current Set state with mutation methods hidden;
+* - [1].add `(value: T) => void` - Adds a value to the set;
+* - [1].remove `(value: T) => void` - Removes a value from the set;
+* - [1].toggle `(value: T) => void` - Adds the value if absent, removes it if present;
+* - [1].setAll `(values: Set<T> | T[]) => void` - Replaces all values in the set;
+* - [1].reset `() => void` - Resets the set to its initial state;
 *
 * @example
 * ```tsx

package/dist/hooks/useStorageState/useStorageState.cjs

@@ -46,7 +46,7 @@ function useStorageState(key, { storage = require_storage.safeLocalStorage, defa
 	const storageState = (0, react.useSyncExternalStore)((onStoreChange) => {
 		listeners.add(onStoreChange);
 		const handler = (event) => {
-			if (event.key === key) onStoreChange();
+			if (event.key == null || event.key === key) onStoreChange();
 		};
 		window.addEventListener("storage", handler);
 		return () => {

package/dist/hooks/useStorageState/useStorageState.d.cts

@@ -17,10 +17,6 @@ type StorageStateOptionsWithSerializer<T> = StorageStateOptions<T> & {
 };
 type SerializableGuard<T extends readonly any[]> = T[0] extends any ? T : T[0] extends never ? 'Received a non-serializable value' : T;
 /**
- * @deprecated This hook is deprecated as it depends on browser-specific APIs (localStorage/sessionStorage).
- * react-simplikit is now focused on platform-independent, pure state/logic hooks.
- * This hook will be removed in a future major version.
- *
  * @description
  * `useStorageState` is a React that functions like `useState` but persists the state value in browser storage.
  * The value is retained across page reloads and can be shared between tabs when using `localStorage`.

package/dist/hooks/useStorageState/useStorageState.d.mts

@@ -17,10 +17,6 @@ type StorageStateOptionsWithSerializer<T> = StorageStateOptions<T> & {
 };
 type SerializableGuard<T extends readonly any[]> = T[0] extends any ? T : T[0] extends never ? 'Received a non-serializable value' : T;
 /**
- * @deprecated This hook is deprecated as it depends on browser-specific APIs (localStorage/sessionStorage).
- * react-simplikit is now focused on platform-independent, pure state/logic hooks.
- * This hook will be removed in a future major version.
- *
  * @description
  * `useStorageState` is a React that functions like `useState` but persists the state value in browser storage.
  * The value is retained across page reloads and can be shared between tabs when using `localStorage`.

package/dist/hooks/useStorageState/useStorageState.mjs

@@ -46,7 +46,7 @@ function useStorageState(key, { storage = safeLocalStorage, defaultValue, ...opt
 	const storageState = useSyncExternalStore((onStoreChange) => {
 		listeners.add(onStoreChange);
 		const handler = (event) => {
-			if (event.key === key) onStoreChange();
+			if (event.key == null || event.key === key) onStoreChange();
 		};
 		window.addEventListener("storage", handler);
 		return () => {

package/dist/hooks/useThrottle/throttle.cjs

@@ -2,17 +2,34 @@
 const require_debounce = require("../useDebounce/debounce.cjs");
 //#region src/hooks/useThrottle/throttle.ts
 function throttle(func, throttleMs, { edges = ["leading", "trailing"] } = {}) {
+	const leading = edges.includes("leading");
+	const trailing = edges.includes("trailing");
 	let pendingAt = null;
-	const debounced = require_debounce.debounce(func, throttleMs, { edges });
+	let isPending = false;
+	const debounced = require_debounce.debounce(function(...args) {
+		pendingAt = Date.now();
+		isPending = false;
+		func.apply(this, args);
+	}, throttleMs, { edges });
 	const throttled = function(...args) {
-		if (pendingAt == null) pendingAt = Date.now();
-		else if (Date.now() - pendingAt >= throttleMs) {
+		if (pendingAt === null) pendingAt = Date.now();
+		const windowElapsed = Date.now() - pendingAt >= throttleMs;
+		if (windowElapsed && (leading || trailing && isPending)) {
 			pendingAt = Date.now();
+			isPending = false;
+			func.apply(this, args);
 			debounced.cancel();
+			debounced.schedule();
+			return;
 		}
-		debounced(...args);
+		if (windowElapsed) pendingAt = Date.now();
+		isPending = true;
+		debounced.apply(this, args);
+	};
+	throttled.cancel = () => {
+		isPending = false;
+		debounced.cancel();
 	};
-	throttled.cancel = debounced.cancel;
 	return throttled;
 }
 //#endregion

package/dist/hooks/useThrottle/throttle.mjs

@@ -2,17 +2,34 @@
 import { debounce } from "../useDebounce/debounce.mjs";
 //#region src/hooks/useThrottle/throttle.ts
 function throttle(func, throttleMs, { edges = ["leading", "trailing"] } = {}) {
+	const leading = edges.includes("leading");
+	const trailing = edges.includes("trailing");
 	let pendingAt = null;
-	const debounced = debounce(func, throttleMs, { edges });
+	let isPending = false;
+	const debounced = debounce(function(...args) {
+		pendingAt = Date.now();
+		isPending = false;
+		func.apply(this, args);
+	}, throttleMs, { edges });
 	const throttled = function(...args) {
-		if (pendingAt == null) pendingAt = Date.now();
-		else if (Date.now() - pendingAt >= throttleMs) {
+		if (pendingAt === null) pendingAt = Date.now();
+		const windowElapsed = Date.now() - pendingAt >= throttleMs;
+		if (windowElapsed && (leading || trailing && isPending)) {
 			pendingAt = Date.now();
+			isPending = false;
+			func.apply(this, args);
 			debounced.cancel();
+			debounced.schedule();
+			return;
 		}
-		debounced(...args);
+		if (windowElapsed) pendingAt = Date.now();
+		isPending = true;
+		debounced.apply(this, args);
+	};
+	throttled.cancel = () => {
+		isPending = false;
+		debounced.cancel();
 	};
-	throttled.cancel = debounced.cancel;
 	return throttled;
 }
 //#endregion

package/dist/hooks/useThrottledCallback/useThrottledCallback.cjs

@@ -1,7 +1,5 @@
 "use client";
-const require_usePreservedCallback = require("../usePreservedCallback/usePreservedCallback.cjs");
-const require_usePreservedReference = require("../usePreservedReference/usePreservedReference.cjs");
-const require_throttle = require("../useThrottle/throttle.cjs");
+const require_useThrottle = require("../useThrottle/useThrottle.cjs");
 let react = require("react");
 //#region src/hooks/useThrottledCallback/useThrottledCallback.ts
 /**
@@ -17,49 +15,36 @@ const NOT_INVOKED = Symbol("NOT_INVOKED");
 * `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.
 *
+* @template T - The type of the value passed to `onChange`.
 * @param {Object} options - The options object.
-* @param {Function} options.onChange - The callback function to throttle.
+* @param {(newValue: T) => void} options.onChange - The callback to throttle. A call with the same value as the last forwarded one is skipped.
 * @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.
+* @returns {(nextValue: T) => void} A throttled function that forwards the value to `onChange` at most once per interval.
 *
 * @example
-* function ScrollTracker() {
-*   const throttledScroll = useThrottledCallback({
-*     onChange: (scrollY: number) => console.log(scrollY),
-*     timeThreshold: 200,
-*   });
-*   return <div onScroll={(e) => throttledScroll(e.currentTarget.scrollTop)} />;
+* import { useThrottledCallback } from 'react-simplikit';
+* import { useState } from 'react';
+*
+* function ScrollPosition() {
+*   const [scrollTop, setScrollTop] = useState(0);
+*   const setScrollTopThrottled = useThrottledCallback({ onChange: setScrollTop, timeThreshold: 200 });
+*
+*   return (
+*     <div onScroll={e => setScrollTopThrottled(e.currentTarget.scrollTop)}>
+*       <p>Scrolled {scrollTop}px</p>
+*     </div>
+*   );
 * }
 */
 function useThrottledCallback({ onChange, timeThreshold, edges = ["leading", "trailing"] }) {
-	const handleChange = require_usePreservedCallback.usePreservedCallback(onChange);
-	const ref = (0, react.useRef)({
-		value: NOT_INVOKED,
-		clearPreviousThrottle: () => {}
-	});
-	(0, react.useEffect)(function cleanupThrottleOnUnmount() {
-		const current = ref.current;
-		return () => {
-			current.clearPreviousThrottle();
-		};
-	}, []);
-	const preservedEdges = require_usePreservedReference.usePreservedReference(edges);
-	return (0, react.useCallback)((nextValue) => {
-		if (nextValue === ref.current.value) return;
-		const throttled = require_throttle.throttle(() => {
-			handleChange(nextValue);
-			ref.current.value = nextValue;
-		}, timeThreshold, { edges: preservedEdges });
-		ref.current.clearPreviousThrottle();
-		throttled();
-		ref.current.clearPreviousThrottle = throttled.cancel;
-	}, [
-		handleChange,
-		timeThreshold,
-		preservedEdges
-	]);
+	const lastForwardedRef = (0, react.useRef)(NOT_INVOKED);
+	return require_useThrottle.useThrottle((nextValue) => {
+		if (nextValue === lastForwardedRef.current) return;
+		onChange(nextValue);
+		lastForwardedRef.current = nextValue;
+	}, timeThreshold, { edges });
 }
 //#endregion
 exports.useThrottledCallback = useThrottledCallback;

package/dist/hooks/useThrottledCallback/useThrottledCallback.d.cts

@@ -8,25 +8,32 @@ type ThrottleOptions = {
  * `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.
  *
+ * @template T - The type of the value passed to `onChange`.
  * @param {Object} options - The options object.
- * @param {Function} options.onChange - The callback function to throttle.
+ * @param {(newValue: T) => void} options.onChange - The callback to throttle. A call with the same value as the last forwarded one is skipped.
  * @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.
+ * @returns {(nextValue: T) => void} A throttled function that forwards the value to `onChange` at most once per interval.
  *
  * @example
- * function ScrollTracker() {
- *   const throttledScroll = useThrottledCallback({
- *     onChange: (scrollY: number) => console.log(scrollY),
- *     timeThreshold: 200,
- *   });
- *   return <div onScroll={(e) => throttledScroll(e.currentTarget.scrollTop)} />;
+ * import { useThrottledCallback } from 'react-simplikit';
+ * import { useState } from 'react';
+ *
+ * function ScrollPosition() {
+ *   const [scrollTop, setScrollTop] = useState(0);
+ *   const setScrollTopThrottled = useThrottledCallback({ onChange: setScrollTop, timeThreshold: 200 });
+ *
+ *   return (
+ *     <div onScroll={e => setScrollTopThrottled(e.currentTarget.scrollTop)}>
+ *       <p>Scrolled {scrollTop}px</p>
+ *     </div>
+ *   );
  * }
  */
-declare function useThrottledCallback({ onChange, timeThreshold, edges }: ThrottleOptions & {
-  onChange: (newValue: boolean) => void;
+declare function useThrottledCallback<T>({ onChange, timeThreshold, edges }: ThrottleOptions & {
+  onChange: (newValue: T) => void;
   timeThreshold: number;
-}): (nextValue: boolean) => void;
+}): (nextValue: T) => void;
 //#endregion
 export { useThrottledCallback };

package/dist/hooks/useThrottledCallback/useThrottledCallback.d.mts

@@ -8,25 +8,32 @@ type ThrottleOptions = {
  * `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.
  *
+ * @template T - The type of the value passed to `onChange`.
  * @param {Object} options - The options object.
- * @param {Function} options.onChange - The callback function to throttle.
+ * @param {(newValue: T) => void} options.onChange - The callback to throttle. A call with the same value as the last forwarded one is skipped.
  * @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.
+ * @returns {(nextValue: T) => void} A throttled function that forwards the value to `onChange` at most once per interval.
  *
  * @example
- * function ScrollTracker() {
- *   const throttledScroll = useThrottledCallback({
- *     onChange: (scrollY: number) => console.log(scrollY),
- *     timeThreshold: 200,
- *   });
- *   return <div onScroll={(e) => throttledScroll(e.currentTarget.scrollTop)} />;
+ * import { useThrottledCallback } from 'react-simplikit';
+ * import { useState } from 'react';
+ *
+ * function ScrollPosition() {
+ *   const [scrollTop, setScrollTop] = useState(0);
+ *   const setScrollTopThrottled = useThrottledCallback({ onChange: setScrollTop, timeThreshold: 200 });
+ *
+ *   return (
+ *     <div onScroll={e => setScrollTopThrottled(e.currentTarget.scrollTop)}>
+ *       <p>Scrolled {scrollTop}px</p>
+ *     </div>
+ *   );
  * }
  */
-declare function useThrottledCallback({ onChange, timeThreshold, edges }: ThrottleOptions & {
-  onChange: (newValue: boolean) => void;
+declare function useThrottledCallback<T>({ onChange, timeThreshold, edges }: ThrottleOptions & {
+  onChange: (newValue: T) => void;
   timeThreshold: number;
-}): (nextValue: boolean) => void;
+}): (nextValue: T) => void;
 //#endregion
 export { useThrottledCallback };

package/dist/hooks/useThrottledCallback/useThrottledCallback.mjs

@@ -1,8 +1,6 @@
 "use client";
-import { usePreservedCallback } from "../usePreservedCallback/usePreservedCallback.mjs";
-import { usePreservedReference } from "../usePreservedReference/usePreservedReference.mjs";
-import { throttle } from "../useThrottle/throttle.mjs";
-import { useCallback, useEffect, useRef } from "react";
+import { useThrottle } from "../useThrottle/useThrottle.mjs";
+import { useRef } from "react";
 //#region src/hooks/useThrottledCallback/useThrottledCallback.ts
 /**
 * Marks that no value has been forwarded to `onChange` yet.
@@ -17,49 +15,36 @@ const NOT_INVOKED = Symbol("NOT_INVOKED");
 * `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.
 *
+* @template T - The type of the value passed to `onChange`.
 * @param {Object} options - The options object.
-* @param {Function} options.onChange - The callback function to throttle.
+* @param {(newValue: T) => void} options.onChange - The callback to throttle. A call with the same value as the last forwarded one is skipped.
 * @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.
+* @returns {(nextValue: T) => void} A throttled function that forwards the value to `onChange` at most once per interval.
 *
 * @example
-* function ScrollTracker() {
-*   const throttledScroll = useThrottledCallback({
-*     onChange: (scrollY: number) => console.log(scrollY),
-*     timeThreshold: 200,
-*   });
-*   return <div onScroll={(e) => throttledScroll(e.currentTarget.scrollTop)} />;
+* import { useThrottledCallback } from 'react-simplikit';
+* import { useState } from 'react';
+*
+* function ScrollPosition() {
+*   const [scrollTop, setScrollTop] = useState(0);
+*   const setScrollTopThrottled = useThrottledCallback({ onChange: setScrollTop, timeThreshold: 200 });
+*
+*   return (
+*     <div onScroll={e => setScrollTopThrottled(e.currentTarget.scrollTop)}>
+*       <p>Scrolled {scrollTop}px</p>
+*     </div>
+*   );
 * }
 */
 function useThrottledCallback({ onChange, timeThreshold, edges = ["leading", "trailing"] }) {
-	const handleChange = usePreservedCallback(onChange);
-	const ref = useRef({
-		value: NOT_INVOKED,
-		clearPreviousThrottle: () => {}
-	});
-	useEffect(function cleanupThrottleOnUnmount() {
-		const current = ref.current;
-		return () => {
-			current.clearPreviousThrottle();
-		};
-	}, []);
-	const preservedEdges = usePreservedReference(edges);
-	return useCallback((nextValue) => {
-		if (nextValue === ref.current.value) return;
-		const throttled = throttle(() => {
-			handleChange(nextValue);
-			ref.current.value = nextValue;
-		}, timeThreshold, { edges: preservedEdges });
-		ref.current.clearPreviousThrottle();
-		throttled();
-		ref.current.clearPreviousThrottle = throttled.cancel;
-	}, [
-		handleChange,
-		timeThreshold,
-		preservedEdges
-	]);
+	const lastForwardedRef = useRef(NOT_INVOKED);
+	return useThrottle((nextValue) => {
+		if (nextValue === lastForwardedRef.current) return;
+		onChange(nextValue);
+		lastForwardedRef.current = nextValue;
+	}, timeThreshold, { edges });
 }
 //#endregion
 export { useThrottledCallback };

package/dist/hooks/useThrottledValue/useThrottledValue.cjs

@@ -0,0 +1,66 @@
+"use client";
+const require_useThrottle = require("../useThrottle/useThrottle.cjs");
+let react = require("react");
+//#region src/hooks/useThrottledValue/useThrottledValue.ts
+/**
+* @description
+* `useThrottledValue` is a React hook that returns a throttled copy of the given value.
+* The caller keeps owning the state; the returned value follows it at most once per `wait` milliseconds,
+* which is useful for driving expensive renders from scroll position, pointer position, or an element's
+* size on resize.
+*
+* On the first render and on the server the value is returned as is. A change is never scheduled
+* on mount, so the first change after mount is applied immediately when `leading` is `true`.
+* If both `leading` and `trailing` are `false`, the returned value never updates.
+*
+* The value is compared by reference. Passing a new object or array on every render keeps
+* the returned value updating every `wait` milliseconds; stabilize the reference first, for
+* example with `usePreservedReference`.
+*
+* @template T - The type of the value.
+* @param {T} value - The value to throttle.
+* @param {number} wait - The length of the throttle window in milliseconds.
+* @param {ThrottleOptions} [options] - Configuration options for throttle behavior.
+* @param {boolean} [options.leading=true] - If `true`, the first change in a window is applied immediately.
+* @param {boolean} [options.trailing=true] - If `true`, the last change in a window is applied `wait` milliseconds after that change.
+*
+* @returns {T} The throttled value.
+*
+* @example
+* import { useThrottledValue } from 'react-simplikit';
+* import { useState } from 'react';
+*
+* function ScrollProgress() {
+*   const [scrollY, setScrollY] = useState(0);
+*   const throttledScrollY = useThrottledValue(scrollY, 100);
+*
+*   return (
+*     <div onScroll={e => setScrollY(e.currentTarget.scrollTop)}>
+*       <ProgressBar position={throttledScrollY} />
+*     </div>
+*   );
+* }
+*/
+function useThrottledValue(value, wait, { leading = true, trailing = true } = {}) {
+	const [throttledValue, setThrottledValue] = (0, react.useState)(() => value);
+	const throttled = require_useThrottle.useThrottle((next) => setThrottledValue(() => next), wait, { edges: toEdges(leading, trailing) });
+	const lastForwardedRef = (0, react.useRef)(value);
+	(0, react.useEffect)(function forwardChangedValue() {
+		if (Object.is(lastForwardedRef.current, value) && Object.is(value, throttledValue)) return;
+		lastForwardedRef.current = value;
+		throttled(value);
+	}, [
+		value,
+		throttledValue,
+		throttled
+	]);
+	return throttledValue;
+}
+function toEdges(leading, trailing) {
+	const edges = [];
+	if (leading) edges.push("leading");
+	if (trailing) edges.push("trailing");
+	return edges;
+}
+//#endregion
+exports.useThrottledValue = useThrottledValue;

package/dist/hooks/useThrottledValue/useThrottledValue.d.cts

@@ -0,0 +1,48 @@
+
+//#region src/hooks/useThrottledValue/useThrottledValue.d.ts
+type ThrottleOptions = {
+  leading?: boolean;
+  trailing?: boolean;
+};
+/**
+ * @description
+ * `useThrottledValue` is a React hook that returns a throttled copy of the given value.
+ * The caller keeps owning the state; the returned value follows it at most once per `wait` milliseconds,
+ * which is useful for driving expensive renders from scroll position, pointer position, or an element's
+ * size on resize.
+ *
+ * On the first render and on the server the value is returned as is. A change is never scheduled
+ * on mount, so the first change after mount is applied immediately when `leading` is `true`.
+ * If both `leading` and `trailing` are `false`, the returned value never updates.
+ *
+ * The value is compared by reference. Passing a new object or array on every render keeps
+ * the returned value updating every `wait` milliseconds; stabilize the reference first, for
+ * example with `usePreservedReference`.
+ *
+ * @template T - The type of the value.
+ * @param {T} value - The value to throttle.
+ * @param {number} wait - The length of the throttle window in milliseconds.
+ * @param {ThrottleOptions} [options] - Configuration options for throttle behavior.
+ * @param {boolean} [options.leading=true] - If `true`, the first change in a window is applied immediately.
+ * @param {boolean} [options.trailing=true] - If `true`, the last change in a window is applied `wait` milliseconds after that change.
+ *
+ * @returns {T} The throttled value.
+ *
+ * @example
+ * import { useThrottledValue } from 'react-simplikit';
+ * import { useState } from 'react';
+ *
+ * function ScrollProgress() {
+ *   const [scrollY, setScrollY] = useState(0);
+ *   const throttledScrollY = useThrottledValue(scrollY, 100);
+ *
+ *   return (
+ *     <div onScroll={e => setScrollY(e.currentTarget.scrollTop)}>
+ *       <ProgressBar position={throttledScrollY} />
+ *     </div>
+ *   );
+ * }
+ */
+declare function useThrottledValue<T>(value: T, wait: number, { leading, trailing }?: ThrottleOptions): T;
+//#endregion
+export { useThrottledValue };