react-simplikit 0.1.0 → 0.3.0

package/dist/hooks/useDebouncedCallback/useDebouncedCallback.mjs

@@ -1,62 +1,57 @@
 "use client";
-import { debounce } from "../useDebounce/debounce.mjs";
-import { usePreservedCallback } from "../usePreservedCallback/usePreservedCallback.mjs";
-import { useCallback, useEffect, useMemo, useRef } from "react";
+import { useDebounce } from "../useDebounce/useDebounce.mjs";
+import { useRef } from "react";
 //#region src/hooks/useDebouncedCallback/useDebouncedCallback.ts
 /**
+* Marks that no value has been forwarded to `onChange` yet.
+*
+* The hook skips redundant invocations by comparing against the last forwarded value, but it
+* receives no initial value from the caller. Seeding that comparison with a real value would treat
+* the first call of that value as redundant and swallow it, so an unreachable sentinel is used instead.
+*/
+const NOT_INVOKED = Symbol("NOT_INVOKED");
+/**
 * @description
 * `useDebouncedCallback` is a React hook that returns a debounced version of the provided callback function.
 * It helps optimize event handling by delaying function execution and grouping multiple calls into one.
 *
 * Note that if both 'leading' and 'trailing' are set, the function will be called at both the start and end of the delay period. However, it must be called at least twice within debounceMs interval for this to happen, since one debounced function call cannot trigger the function twice.
 *
+* @template T - The type of the value passed to `onChange`.
 * @param {Object} options - The options object.
-* @param {Function} options.onChange - The callback function to debounce.
+* @param {(newValue: T) => void} options.onChange - The callback to debounce. A call with the same value as the last forwarded one is skipped.
 * @param {number} options.timeThreshold - The number of milliseconds to delay the function execution.
 * @param {boolean} [options.leading=false] - If `true`, the function is called at the start of the sequence.
 * @param {boolean} [options.trailing=true] - If `true`, the function is called at the end of the sequence.
 *
-* @returns {Function} A debounced function that delays invoking the callback.
+* @returns {(nextValue: T) => void} A debounced function that forwards the value to `onChange`.
 *
 * @example
+* import { useDebouncedCallback } from 'react-simplikit';
+* import { useState } from 'react';
+*
 * function SearchInput() {
 *   const [query, setQuery] = useState('');
-*   const debouncedSetQuery = useDebouncedCallback({ onChange: setQuery, timeThreshold: 100 });
-*   return <input type="text" onChange={(e) => debouncedSetQuery(e.target.value)} />;
+*   const setQueryDebounced = useDebouncedCallback({ onChange: setQuery, timeThreshold: 300 });
+*
+*   return (
+*     <>
+*       <input onChange={e => setQueryDebounced(e.target.value)} />
+*       <p>Searching for: {query}</p>
+*     </>
+*   );
 * }
 */
 function useDebouncedCallback({ onChange, timeThreshold, leading = false, trailing = true }) {
-	const handleChange = usePreservedCallback(onChange);
-	const ref = useRef({
-		value: false,
-		clearPreviousDebounce: () => {}
+	const lastForwardedRef = useRef(NOT_INVOKED);
+	return useDebounce((nextValue) => {
+		if (nextValue === lastForwardedRef.current) return;
+		onChange(nextValue);
+		lastForwardedRef.current = nextValue;
+	}, timeThreshold, {
+		leading,
+		trailing
 	});
-	useEffect(function clearDebouncedOnUnmount() {
-		const current = ref.current;
-		return () => {
-			current.clearPreviousDebounce();
-		};
-	}, []);
-	const edges = useMemo(() => {
-		const _edges = [];
-		if (leading) _edges.push("leading");
-		if (trailing) _edges.push("trailing");
-		return _edges;
-	}, [leading, trailing]);
-	return useCallback((nextValue) => {
-		if (nextValue === ref.current.value) return;
-		const debounced = debounce(() => {
-			handleChange(nextValue);
-			ref.current.value = nextValue;
-		}, timeThreshold, { edges });
-		ref.current.clearPreviousDebounce();
-		debounced();
-		ref.current.clearPreviousDebounce = debounced.cancel;
-	}, [
-		handleChange,
-		timeThreshold,
-		edges
-	]);
 }
 //#endregion
 export { useDebouncedCallback };

package/dist/hooks/useDebouncedValue/useDebouncedValue.cjs

@@ -0,0 +1,64 @@
+"use client";
+const require_useDebounce = require("../useDebounce/useDebounce.cjs");
+let react = require("react");
+//#region src/hooks/useDebouncedValue/useDebouncedValue.ts
+/**
+* @description
+* `useDebouncedValue` is a React hook that returns a debounced copy of the given value.
+* The caller keeps owning the state; the hook only delays how quickly the returned value follows it.
+* The returned value updates `wait` milliseconds after the last change, which is useful for
+* deriving a search query or a validation input from fast-changing state.
+*
+* On the first render and on the server the value is returned as is. A change is never scheduled
+* on mount, so with `leading: true` the first change after mount is applied immediately.
+* 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 debounce.
+* @param {number} wait - The number of milliseconds to wait after the last change before updating.
+* @param {DebounceOptions} [options] - Configuration options for debounce behavior.
+* @param {boolean} [options.leading=false] - If `true`, the first change after an idle period is applied immediately.
+* @param {boolean} [options.trailing=true] - If `true`, the last change is applied after `wait` milliseconds.
+*
+* @returns {T} The debounced value.
+*
+* @example
+* import { useDebouncedValue } from 'react-simplikit';
+* import { useState } from 'react';
+*
+* function SearchInput() {
+*   const [query, setQuery] = useState('');
+*   const debouncedQuery = useDebouncedValue(query, 300);
+*
+*   return (
+*     <>
+*       <input value={query} onChange={e => setQuery(e.target.value)} />
+*       <SearchResults query={debouncedQuery} />
+*     </>
+*   );
+* }
+*/
+function useDebouncedValue(value, wait, { leading = false, trailing = true } = {}) {
+	const [debouncedValue, setDebouncedValue] = (0, react.useState)(() => value);
+	const debounced = require_useDebounce.useDebounce((next) => setDebouncedValue(() => next), wait, {
+		leading,
+		trailing
+	});
+	const lastForwardedRef = (0, react.useRef)(value);
+	(0, react.useEffect)(function forwardChangedValue() {
+		if (Object.is(lastForwardedRef.current, value) && Object.is(value, debouncedValue)) return;
+		lastForwardedRef.current = value;
+		debounced(value);
+	}, [
+		value,
+		debouncedValue,
+		debounced
+	]);
+	return debouncedValue;
+}
+//#endregion
+exports.useDebouncedValue = useDebouncedValue;

package/dist/hooks/useDebouncedValue/useDebouncedValue.d.cts

@@ -0,0 +1,49 @@
+
+//#region src/hooks/useDebouncedValue/useDebouncedValue.d.ts
+type DebounceOptions = {
+  leading?: boolean;
+  trailing?: boolean;
+};
+/**
+ * @description
+ * `useDebouncedValue` is a React hook that returns a debounced copy of the given value.
+ * The caller keeps owning the state; the hook only delays how quickly the returned value follows it.
+ * The returned value updates `wait` milliseconds after the last change, which is useful for
+ * deriving a search query or a validation input from fast-changing state.
+ *
+ * On the first render and on the server the value is returned as is. A change is never scheduled
+ * on mount, so with `leading: true` the first change after mount is applied immediately.
+ * 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 debounce.
+ * @param {number} wait - The number of milliseconds to wait after the last change before updating.
+ * @param {DebounceOptions} [options] - Configuration options for debounce behavior.
+ * @param {boolean} [options.leading=false] - If `true`, the first change after an idle period is applied immediately.
+ * @param {boolean} [options.trailing=true] - If `true`, the last change is applied after `wait` milliseconds.
+ *
+ * @returns {T} The debounced value.
+ *
+ * @example
+ * import { useDebouncedValue } from 'react-simplikit';
+ * import { useState } from 'react';
+ *
+ * function SearchInput() {
+ *   const [query, setQuery] = useState('');
+ *   const debouncedQuery = useDebouncedValue(query, 300);
+ *
+ *   return (
+ *     <>
+ *       <input value={query} onChange={e => setQuery(e.target.value)} />
+ *       <SearchResults query={debouncedQuery} />
+ *     </>
+ *   );
+ * }
+ */
+declare function useDebouncedValue<T>(value: T, wait: number, { leading, trailing }?: DebounceOptions): T;
+//#endregion
+export { useDebouncedValue };

package/dist/hooks/useDebouncedValue/useDebouncedValue.d.mts

@@ -0,0 +1,49 @@
+
+//#region src/hooks/useDebouncedValue/useDebouncedValue.d.ts
+type DebounceOptions = {
+  leading?: boolean;
+  trailing?: boolean;
+};
+/**
+ * @description
+ * `useDebouncedValue` is a React hook that returns a debounced copy of the given value.
+ * The caller keeps owning the state; the hook only delays how quickly the returned value follows it.
+ * The returned value updates `wait` milliseconds after the last change, which is useful for
+ * deriving a search query or a validation input from fast-changing state.
+ *
+ * On the first render and on the server the value is returned as is. A change is never scheduled
+ * on mount, so with `leading: true` the first change after mount is applied immediately.
+ * 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 debounce.
+ * @param {number} wait - The number of milliseconds to wait after the last change before updating.
+ * @param {DebounceOptions} [options] - Configuration options for debounce behavior.
+ * @param {boolean} [options.leading=false] - If `true`, the first change after an idle period is applied immediately.
+ * @param {boolean} [options.trailing=true] - If `true`, the last change is applied after `wait` milliseconds.
+ *
+ * @returns {T} The debounced value.
+ *
+ * @example
+ * import { useDebouncedValue } from 'react-simplikit';
+ * import { useState } from 'react';
+ *
+ * function SearchInput() {
+ *   const [query, setQuery] = useState('');
+ *   const debouncedQuery = useDebouncedValue(query, 300);
+ *
+ *   return (
+ *     <>
+ *       <input value={query} onChange={e => setQuery(e.target.value)} />
+ *       <SearchResults query={debouncedQuery} />
+ *     </>
+ *   );
+ * }
+ */
+declare function useDebouncedValue<T>(value: T, wait: number, { leading, trailing }?: DebounceOptions): T;
+//#endregion
+export { useDebouncedValue };

package/dist/hooks/useDebouncedValue/useDebouncedValue.mjs

@@ -0,0 +1,64 @@
+"use client";
+import { useDebounce } from "../useDebounce/useDebounce.mjs";
+import { useEffect, useRef, useState } from "react";
+//#region src/hooks/useDebouncedValue/useDebouncedValue.ts
+/**
+* @description
+* `useDebouncedValue` is a React hook that returns a debounced copy of the given value.
+* The caller keeps owning the state; the hook only delays how quickly the returned value follows it.
+* The returned value updates `wait` milliseconds after the last change, which is useful for
+* deriving a search query or a validation input from fast-changing state.
+*
+* On the first render and on the server the value is returned as is. A change is never scheduled
+* on mount, so with `leading: true` the first change after mount is applied immediately.
+* 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 debounce.
+* @param {number} wait - The number of milliseconds to wait after the last change before updating.
+* @param {DebounceOptions} [options] - Configuration options for debounce behavior.
+* @param {boolean} [options.leading=false] - If `true`, the first change after an idle period is applied immediately.
+* @param {boolean} [options.trailing=true] - If `true`, the last change is applied after `wait` milliseconds.
+*
+* @returns {T} The debounced value.
+*
+* @example
+* import { useDebouncedValue } from 'react-simplikit';
+* import { useState } from 'react';
+*
+* function SearchInput() {
+*   const [query, setQuery] = useState('');
+*   const debouncedQuery = useDebouncedValue(query, 300);
+*
+*   return (
+*     <>
+*       <input value={query} onChange={e => setQuery(e.target.value)} />
+*       <SearchResults query={debouncedQuery} />
+*     </>
+*   );
+* }
+*/
+function useDebouncedValue(value, wait, { leading = false, trailing = true } = {}) {
+	const [debouncedValue, setDebouncedValue] = useState(() => value);
+	const debounced = useDebounce((next) => setDebouncedValue(() => next), wait, {
+		leading,
+		trailing
+	});
+	const lastForwardedRef = useRef(value);
+	useEffect(function forwardChangedValue() {
+		if (Object.is(lastForwardedRef.current, value) && Object.is(value, debouncedValue)) return;
+		lastForwardedRef.current = value;
+		debounced(value);
+	}, [
+		value,
+		debouncedValue,
+		debounced
+	]);
+	return debouncedValue;
+}
+//#endregion
+export { useDebouncedValue };

package/dist/hooks/useDoubleClick/useDoubleClick.cjs

@@ -3,10 +3,6 @@ const require_usePreservedCallback = require("../usePreservedCallback/usePreserv
 let react = require("react");
 //#region src/hooks/useDoubleClick/useDoubleClick.ts
 /**
-* @deprecated This hook is deprecated as it depends on browser-specific APIs (DOM events, window.setTimeout).
-* react-simplikit is now focused on platform-independent, pure state/logic hooks.
-* This hook will be removed in a future major version.
-*
 * @description
 * `useDoubleClick` is a React hook that differentiates between single and double click events.
 * It delays the single click callback execution for a specified time, and cancels it if a second click (i.e. a double click) occurs within that time.

package/dist/hooks/useDoubleClick/useDoubleClick.d.cts

@@ -7,10 +7,6 @@ type UseDoubleClickProps<E extends HTMLElement> = {
   doubleClick: (event: MouseEvent<E>) => void;
 };
 /**
- * @deprecated This hook is deprecated as it depends on browser-specific APIs (DOM events, window.setTimeout).
- * react-simplikit is now focused on platform-independent, pure state/logic hooks.
- * This hook will be removed in a future major version.
- *
  * @description
  * `useDoubleClick` is a React hook that differentiates between single and double click events.
  * It delays the single click callback execution for a specified time, and cancels it if a second click (i.e. a double click) occurs within that time.

package/dist/hooks/useDoubleClick/useDoubleClick.d.mts

@@ -7,10 +7,6 @@ type UseDoubleClickProps<E extends HTMLElement> = {
   doubleClick: (event: MouseEvent<E>) => void;
 };
 /**
- * @deprecated This hook is deprecated as it depends on browser-specific APIs (DOM events, window.setTimeout).
- * react-simplikit is now focused on platform-independent, pure state/logic hooks.
- * This hook will be removed in a future major version.
- *
  * @description
  * `useDoubleClick` is a React hook that differentiates between single and double click events.
  * It delays the single click callback execution for a specified time, and cancels it if a second click (i.e. a double click) occurs within that time.

package/dist/hooks/useDoubleClick/useDoubleClick.mjs

@@ -3,10 +3,6 @@ import { usePreservedCallback } from "../usePreservedCallback/usePreservedCallba
 import { useCallback, useEffect, useRef } from "react";
 //#region src/hooks/useDoubleClick/useDoubleClick.ts
 /**
-* @deprecated This hook is deprecated as it depends on browser-specific APIs (DOM events, window.setTimeout).
-* react-simplikit is now focused on platform-independent, pure state/logic hooks.
-* This hook will be removed in a future major version.
-*
 * @description
 * `useDoubleClick` is a React hook that differentiates between single and double click events.
 * It delays the single click callback execution for a specified time, and cancels it if a second click (i.e. a double click) occurs within that time.

package/dist/hooks/useGeolocation/useGeolocation.cjs

@@ -14,10 +14,6 @@ const GeolocationMountBehavior = {
 	WATCH: "watch"
 };
 /**
-* @deprecated This hook is deprecated as it depends on browser-specific APIs (navigator.geolocation).
-* react-simplikit is now focused on platform-independent, pure state/logic hooks.
-* This hook will be removed in a future major version.
-*
 * @description
 * `useGeolocation` is a React hook that retrieves and tracks the user's geographical location.
 * It uses the browser's `Geolocation API` to support both one-time position retrieval and continuous location tracking.

package/dist/hooks/useGeolocation/useGeolocation.d.cts

@@ -26,10 +26,6 @@ type GeolocationOptions = {
   mountBehavior?: GeolocationMountBehaviorType;
 } & PositionOptions;
 /**
- * @deprecated This hook is deprecated as it depends on browser-specific APIs (navigator.geolocation).
- * react-simplikit is now focused on platform-independent, pure state/logic hooks.
- * This hook will be removed in a future major version.
- *
  * @description
  * `useGeolocation` is a React hook that retrieves and tracks the user's geographical location.
  * It uses the browser's `Geolocation API` to support both one-time position retrieval and continuous location tracking.

package/dist/hooks/useGeolocation/useGeolocation.d.mts

@@ -26,10 +26,6 @@ type GeolocationOptions = {
   mountBehavior?: GeolocationMountBehaviorType;
 } & PositionOptions;
 /**
- * @deprecated This hook is deprecated as it depends on browser-specific APIs (navigator.geolocation).
- * react-simplikit is now focused on platform-independent, pure state/logic hooks.
- * This hook will be removed in a future major version.
- *
  * @description
  * `useGeolocation` is a React hook that retrieves and tracks the user's geographical location.
  * It uses the browser's `Geolocation API` to support both one-time position retrieval and continuous location tracking.

package/dist/hooks/useGeolocation/useGeolocation.mjs

@@ -14,10 +14,6 @@ const GeolocationMountBehavior = {
 	WATCH: "watch"
 };
 /**
-* @deprecated This hook is deprecated as it depends on browser-specific APIs (navigator.geolocation).
-* react-simplikit is now focused on platform-independent, pure state/logic hooks.
-* This hook will be removed in a future major version.
-*
 * @description
 * `useGeolocation` is a React hook that retrieves and tracks the user's geographical location.
 * It uses the browser's `Geolocation API` to support both one-time position retrieval and continuous location tracking.

package/dist/hooks/useImpressionRef/useImpressionRef.cjs

@@ -6,10 +6,6 @@ const require_useVisibilityEvent = require("../useVisibilityEvent/useVisibilityE
 let react = require("react");
 //#region src/hooks/useImpressionRef/useImpressionRef.ts
 /**
-* @deprecated This hook is deprecated as it depends on browser-specific APIs (IntersectionObserver, Visibility API).
-* react-simplikit is now focused on platform-independent, pure state/logic hooks.
-* This hook will be removed in a future major version.
-*
 * @description
 * `useImpressionRef` is a React hook that measures the time a specific DOM element is visible on the screen and executes callbacks when the element enters or exits the viewport.
 * It uses `IntersectionObserver` and the `Visibility API` to track the element's visibility.
@@ -41,23 +37,45 @@ function useImpressionRef({ onImpressionStart = () => {}, onImpressionEnd = () =
 	const impressionStartHandler = require_usePreservedCallback.usePreservedCallback(onImpressionStart);
 	const impressionEndHandler = require_usePreservedCallback.usePreservedCallback(onImpressionEnd);
 	const isIntersectingRef = (0, react.useRef)(false);
+	const requestedImpressionRef = (0, react.useRef)(false);
+	const hasImpressionStartedRef = (0, react.useRef)(false);
 	const impressionEventHandler = require_useDebouncedCallback.useDebouncedCallback({
 		timeThreshold,
 		onChange: (impressed) => {
-			(impressed ? impressionStartHandler : impressionEndHandler)();
+			if (impressed) {
+				hasImpressionStartedRef.current = true;
+				impressionStartHandler();
+				return;
+			}
+			if (hasImpressionStartedRef.current) {
+				hasImpressionStartedRef.current = false;
+				impressionEndHandler();
+			}
 		},
 		leading: true
 	});
+	const requestImpressionChange = (impressed) => {
+		requestedImpressionRef.current = impressed;
+		impressionEventHandler(impressed);
+	};
+	(0, react.useEffect)(function emitPendingImpressionEndOnUnmount() {
+		return () => {
+			if (hasImpressionStartedRef.current && !requestedImpressionRef.current) {
+				hasImpressionStartedRef.current = false;
+				impressionEndHandler();
+			}
+		};
+	}, [impressionEndHandler]);
 	require_useVisibilityEvent.useVisibilityEvent((documentVisible) => {
 		if (!isIntersectingRef.current) return;
-		impressionEventHandler(documentVisible === "visible");
+		requestImpressionChange(documentVisible === "visible");
 	});
 	return require_useIntersectionObserver.useIntersectionObserver((entry) => {
 		if (document.visibilityState === "hidden") return;
 		const currentRatio = entry.intersectionRatio;
 		const isIntersecting = areaThreshold === 0 ? entry.isIntersecting : currentRatio >= areaThreshold;
 		isIntersectingRef.current = isIntersecting;
-		impressionEventHandler(isIntersecting);
+		requestImpressionChange(isIntersecting);
 	}, {
 		rootMargin,
 		threshold: areaThreshold

package/dist/hooks/useImpressionRef/useImpressionRef.d.cts

@@ -8,10 +8,6 @@ type UseImpressionRefOptions = Partial<{
   timeThreshold: number;
 }>;
 /**
- * @deprecated This hook is deprecated as it depends on browser-specific APIs (IntersectionObserver, Visibility API).
- * react-simplikit is now focused on platform-independent, pure state/logic hooks.
- * This hook will be removed in a future major version.
- *
  * @description
  * `useImpressionRef` is a React hook that measures the time a specific DOM element is visible on the screen and executes callbacks when the element enters or exits the viewport.
  * It uses `IntersectionObserver` and the `Visibility API` to track the element's visibility.

package/dist/hooks/useImpressionRef/useImpressionRef.d.mts

@@ -8,10 +8,6 @@ type UseImpressionRefOptions = Partial<{
   timeThreshold: number;
 }>;
 /**
- * @deprecated This hook is deprecated as it depends on browser-specific APIs (IntersectionObserver, Visibility API).
- * react-simplikit is now focused on platform-independent, pure state/logic hooks.
- * This hook will be removed in a future major version.
- *
  * @description
  * `useImpressionRef` is a React hook that measures the time a specific DOM element is visible on the screen and executes callbacks when the element enters or exits the viewport.
  * It uses `IntersectionObserver` and the `Visibility API` to track the element's visibility.

package/dist/hooks/useImpressionRef/useImpressionRef.mjs

@@ -3,13 +3,9 @@ import { usePreservedCallback } from "../usePreservedCallback/usePreservedCallba
 import { useDebouncedCallback } from "../useDebouncedCallback/useDebouncedCallback.mjs";
 import { useIntersectionObserver } from "../useIntersectionObserver/useIntersectionObserver.mjs";
 import { useVisibilityEvent } from "../useVisibilityEvent/useVisibilityEvent.mjs";
-import { useRef } from "react";
+import { useEffect, useRef } from "react";
 //#region src/hooks/useImpressionRef/useImpressionRef.ts
 /**
-* @deprecated This hook is deprecated as it depends on browser-specific APIs (IntersectionObserver, Visibility API).
-* react-simplikit is now focused on platform-independent, pure state/logic hooks.
-* This hook will be removed in a future major version.
-*
 * @description
 * `useImpressionRef` is a React hook that measures the time a specific DOM element is visible on the screen and executes callbacks when the element enters or exits the viewport.
 * It uses `IntersectionObserver` and the `Visibility API` to track the element's visibility.
@@ -41,23 +37,45 @@ function useImpressionRef({ onImpressionStart = () => {}, onImpressionEnd = () =
 	const impressionStartHandler = usePreservedCallback(onImpressionStart);
 	const impressionEndHandler = usePreservedCallback(onImpressionEnd);
 	const isIntersectingRef = useRef(false);
+	const requestedImpressionRef = useRef(false);
+	const hasImpressionStartedRef = useRef(false);
 	const impressionEventHandler = useDebouncedCallback({
 		timeThreshold,
 		onChange: (impressed) => {
-			(impressed ? impressionStartHandler : impressionEndHandler)();
+			if (impressed) {
+				hasImpressionStartedRef.current = true;
+				impressionStartHandler();
+				return;
+			}
+			if (hasImpressionStartedRef.current) {
+				hasImpressionStartedRef.current = false;
+				impressionEndHandler();
+			}
 		},
 		leading: true
 	});
+	const requestImpressionChange = (impressed) => {
+		requestedImpressionRef.current = impressed;
+		impressionEventHandler(impressed);
+	};
+	useEffect(function emitPendingImpressionEndOnUnmount() {
+		return () => {
+			if (hasImpressionStartedRef.current && !requestedImpressionRef.current) {
+				hasImpressionStartedRef.current = false;
+				impressionEndHandler();
+			}
+		};
+	}, [impressionEndHandler]);
 	useVisibilityEvent((documentVisible) => {
 		if (!isIntersectingRef.current) return;
-		impressionEventHandler(documentVisible === "visible");
+		requestImpressionChange(documentVisible === "visible");
 	});
 	return useIntersectionObserver((entry) => {
 		if (document.visibilityState === "hidden") return;
 		const currentRatio = entry.intersectionRatio;
 		const isIntersecting = areaThreshold === 0 ? entry.isIntersecting : currentRatio >= areaThreshold;
 		isIntersectingRef.current = isIntersecting;
-		impressionEventHandler(isIntersecting);
+		requestImpressionChange(isIntersecting);
 	}, {
 		rootMargin,
 		threshold: areaThreshold

package/dist/hooks/useInputState/useInputState.cjs

@@ -6,7 +6,7 @@ let react = require("react");
 * `useInputState` is a React hook that manages an input state with optional value transformation.
 * The returned `onChange` handler works with both `<input>` and `<textarea>` elements.
 *
-* @param {string} [initialValue=""] - The initial value of the input. Defaults to an empty string (`""`).
+* @param {string | (() => string)} [initialValue=""] - The initial value of the input. Defaults to an empty string (`""`).
 * @param {(value: string) => string} [transformValue=(v: string) => v] - A function to transform the input value.
 *   Defaults to an identity function that returns the input unchanged.
 *

package/dist/hooks/useInputState/useInputState.d.cts

@@ -2,12 +2,13 @@
 import { ChangeEventHandler } from "react";
 //#region src/hooks/useInputState/useInputState.d.ts
 type InputLikeElement = HTMLInputElement | HTMLTextAreaElement;
+type InitialValue = string | (() => string);
 /**
  * @description
  * `useInputState` is a React hook that manages an input state with optional value transformation.
  * The returned `onChange` handler works with both `<input>` and `<textarea>` elements.
  *
- * @param {string} [initialValue=""] - The initial value of the input. Defaults to an empty string (`""`).
+ * @param {string | (() => string)} [initialValue=""] - The initial value of the input. Defaults to an empty string (`""`).
  * @param {(value: string) => string} [transformValue=(v: string) => v] - A function to transform the input value.
  *   Defaults to an identity function that returns the input unchanged.
  *
@@ -26,6 +27,6 @@ type InputLikeElement = HTMLInputElement | HTMLTextAreaElement;
  *   );
  * }
  */
-declare function useInputState(initialValue?: string, transformValue?: (value: string) => string): readonly [string, ChangeEventHandler<InputLikeElement>];
+declare function useInputState(initialValue?: InitialValue, transformValue?: (value: string) => string): readonly [string, ChangeEventHandler<InputLikeElement>];
 //#endregion
 export { useInputState };

package/dist/hooks/useInputState/useInputState.d.mts

@@ -2,12 +2,13 @@
 import { ChangeEventHandler } from "react";
 //#region src/hooks/useInputState/useInputState.d.ts
 type InputLikeElement = HTMLInputElement | HTMLTextAreaElement;
+type InitialValue = string | (() => string);
 /**
  * @description
  * `useInputState` is a React hook that manages an input state with optional value transformation.
  * The returned `onChange` handler works with both `<input>` and `<textarea>` elements.
  *
- * @param {string} [initialValue=""] - The initial value of the input. Defaults to an empty string (`""`).
+ * @param {string | (() => string)} [initialValue=""] - The initial value of the input. Defaults to an empty string (`""`).
  * @param {(value: string) => string} [transformValue=(v: string) => v] - A function to transform the input value.
  *   Defaults to an identity function that returns the input unchanged.
  *
@@ -26,6 +27,6 @@ type InputLikeElement = HTMLInputElement | HTMLTextAreaElement;
  *   );
  * }
  */
-declare function useInputState(initialValue?: string, transformValue?: (value: string) => string): readonly [string, ChangeEventHandler<InputLikeElement>];
+declare function useInputState(initialValue?: InitialValue, transformValue?: (value: string) => string): readonly [string, ChangeEventHandler<InputLikeElement>];
 //#endregion
 export { useInputState };

package/dist/hooks/useInputState/useInputState.mjs

@@ -6,7 +6,7 @@ import { useCallback, useState } from "react";
 * `useInputState` is a React hook that manages an input state with optional value transformation.
 * The returned `onChange` handler works with both `<input>` and `<textarea>` elements.
 *
-* @param {string} [initialValue=""] - The initial value of the input. Defaults to an empty string (`""`).
+* @param {string | (() => string)} [initialValue=""] - The initial value of the input. Defaults to an empty string (`""`).
 * @param {(value: string) => string} [transformValue=(v: string) => v] - A function to transform the input value.
 *   Defaults to an identity function that returns the input unchanged.
 *