@aweebit/react-essentials 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Wee Bit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/hooks/useDerivedState.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @file Based on {@link https://github.com/peterjuras/use-state-with-deps}
+ *
+ * @license MIT
+ *
+ * Copyright (c) 2020 Peter Juras
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+import { type DependencyList, type Dispatch, type SetStateAction } from 'react';
+/**
+ * `useState` hook with an additional dependency array that resets
+ * the state to the `initialState` param when the dependencies passed
+ * in the `deps` array change.
+ *
+ * @param initialState
+ * The state that will be set when the component mounts or the
+ * dependencies change.
+ *
+ * It can also be a function which resolves to the state. If the state
+ * is reset due to a change of dependencies, this function will be called with the previous
+ * state (`undefined` for the first call upon mount).
+ * @param deps Dependencies for this hook that resets the state to `initialState`
+ */
+export default function useDerivedState<S>(initialState: S | ((previousState?: S) => S), deps: DependencyList): [S, Dispatch<SetStateAction<S>>];
+//# sourceMappingURL=useDerivedState.d.ts.map

package/dist/hooks/useDerivedState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDerivedState.d.ts","sourceRoot":"","sources":["../../lib/hooks/useDerivedState.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,cAAc,EACpB,MAAM,OAAO,CAAC;AAIf;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,OAAO,UAAU,eAAe,CAAC,CAAC,EACvC,YAAY,EAAE,CAAC,GAAG,CAAC,CAAC,aAAa,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAC5C,IAAI,EAAE,cAAc,GACnB,CAAC,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAsDlC"}

package/dist/hooks/useDerivedState.js

@@ -0,0 +1,92 @@
+/**
+ * @file Based on {@link https://github.com/peterjuras/use-state-with-deps}
+ *
+ * @license MIT
+ *
+ * Copyright (c) 2020 Peter Juras
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+import { useCallback, useRef, } from 'react';
+import { depsAreEqual, isFunction } from '../utils';
+import useForceUpdate from './useForceUpdate';
+/**
+ * `useState` hook with an additional dependency array that resets
+ * the state to the `initialState` param when the dependencies passed
+ * in the `deps` array change.
+ *
+ * @param initialState
+ * The state that will be set when the component mounts or the
+ * dependencies change.
+ *
+ * It can also be a function which resolves to the state. If the state
+ * is reset due to a change of dependencies, this function will be called with the previous
+ * state (`undefined` for the first call upon mount).
+ * @param deps Dependencies for this hook that resets the state to `initialState`
+ */
+export default function useDerivedState(initialState, deps) {
+    const isMounted = useRef(false);
+    // Determine initial state
+    let usableInitialState = null;
+    if (!isMounted.current) {
+        isMounted.current = true;
+        if (isFunction(initialState)) {
+            usableInitialState = initialState();
+        }
+        else {
+            usableInitialState = initialState;
+        }
+    }
+    // It would be possible to use useState instead of
+    // useRef to store the state, however this would
+    // trigger re-renders whenever the state is reset due
+    // to a change in dependencies. In order to avoid these
+    // re-renders, the state is stored in a ref and an
+    // update is triggered via forceUpdate below when necessary
+    const state = useRef(usableInitialState);
+    // Check if dependencies have changed
+    const prevDeps = useRef(deps);
+    if (!depsAreEqual(prevDeps.current, deps)) {
+        // Update state and deps
+        let nextState;
+        if (isFunction(initialState)) {
+            nextState = initialState(state.current);
+        }
+        else {
+            nextState = initialState;
+        }
+        state.current = nextState;
+        prevDeps.current = deps;
+    }
+    const [forceUpdate] = useForceUpdate();
+    const updateState = useCallback(function updateState(newState) {
+        let nextState;
+        if (isFunction(newState)) {
+            nextState = newState(state.current);
+        }
+        else {
+            nextState = newState;
+        }
+        if (!Object.is(state.current, nextState)) {
+            state.current = nextState;
+            forceUpdate();
+        }
+    }, []); // eslint-disable-line react-hooks/exhaustive-deps
+    return [state.current, updateState];
+}

package/dist/hooks/useEventListener.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @file Based on {@link https://github.com/juliencrn/usehooks-ts}
+ *
+ * @license MIT
+ *
+ * Copyright (c) 2020 Julien CARON
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+/**
+ * Adds `handler` as a listener for the event `eventName` of `element`
+ * (or `window` by default) with the provided `options` applied.
+ *
+ * It is the user's responsibility to make sure `element` and `options` values
+ * are correctly memoized!
+ */
+declare function useEventListener<K extends keyof SVGElementEventMap, T extends SVGElement>(eventName: K, handler: (event: SVGElementEventMap[K]) => void, element: T, options?: boolean | AddEventListenerOptions): void;
+declare function useEventListener<K extends keyof HTMLElementEventMap, T extends HTMLElement>(eventName: K, handler: (event: HTMLElementEventMap[K]) => void, element: T, options?: boolean | AddEventListenerOptions): void;
+declare function useEventListener<K extends keyof DocumentEventMap>(eventName: K, handler: (event: DocumentEventMap[K]) => void, element: Document, options?: boolean | AddEventListenerOptions): void;
+declare function useEventListener<K extends keyof WindowEventMap>(eventName: K, handler: (event: WindowEventMap[K]) => void, element?: Window, options?: boolean | AddEventListenerOptions): void;
+export default useEventListener;
+//# sourceMappingURL=useEventListener.d.ts.map

package/dist/hooks/useEventListener.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useEventListener.d.ts","sourceRoot":"","sources":["../../lib/hooks/useEventListener.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAIH;;;;;;GAMG;AAGH,iBAAS,gBAAgB,CACvB,CAAC,SAAS,MAAM,kBAAkB,EAClC,CAAC,SAAS,UAAU,EAEpB,SAAS,EAAE,CAAC,EACZ,OAAO,EAAE,CAAC,KAAK,EAAE,kBAAkB,CAAC,CAAC,CAAC,KAAK,IAAI,EAC/C,OAAO,EAAE,CAAC,EACV,OAAO,CAAC,EAAE,OAAO,GAAG,uBAAuB,GAC1C,IAAI,CAAC;AAGR,iBAAS,gBAAgB,CACvB,CAAC,SAAS,MAAM,mBAAmB,EACnC,CAAC,SAAS,WAAW,EAErB,SAAS,EAAE,CAAC,EACZ,OAAO,EAAE,CAAC,KAAK,EAAE,mBAAmB,CAAC,CAAC,CAAC,KAAK,IAAI,EAChD,OAAO,EAAE,CAAC,EACV,OAAO,CAAC,EAAE,OAAO,GAAG,uBAAuB,GAC1C,IAAI,CAAC;AAGR,iBAAS,gBAAgB,CAAC,CAAC,SAAS,MAAM,gBAAgB,EACxD,SAAS,EAAE,CAAC,EACZ,OAAO,EAAE,CAAC,KAAK,EAAE,gBAAgB,CAAC,CAAC,CAAC,KAAK,IAAI,EAC7C,OAAO,EAAE,QAAQ,EACjB,OAAO,CAAC,EAAE,OAAO,GAAG,uBAAuB,GAC1C,IAAI,CAAC;AAGR,iBAAS,gBAAgB,CAAC,CAAC,SAAS,MAAM,cAAc,EACtD,SAAS,EAAE,CAAC,EACZ,OAAO,EAAE,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,KAAK,IAAI,EAC3C,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,OAAO,GAAG,uBAAuB,GAC1C,IAAI,CAAC;AAiCR,eAAe,gBAAgB,CAAC"}

package/dist/hooks/useEventListener.js

@@ -0,0 +1,47 @@
+/**
+ * @file Based on {@link https://github.com/juliencrn/usehooks-ts}
+ *
+ * @license MIT
+ *
+ * Copyright (c) 2020 Julien CARON
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+import { useEffect, useLayoutEffect, useRef } from 'react';
+function useEventListener(eventName, handler, element, options) {
+    // Create a ref that stores handler
+    const savedHandler = useRef(handler);
+    useLayoutEffect(() => {
+        savedHandler.current = handler;
+    }, [handler]);
+    useEffect(() => {
+        // Define the listening target
+        const targetElement = element ?? window;
+        // Create event listener that calls handler function stored in ref
+        const listener = (event) => {
+            savedHandler.current(event);
+        };
+        targetElement.addEventListener(eventName, listener, options);
+        // Remove event listener on cleanup
+        return () => {
+            targetElement.removeEventListener(eventName, listener, options);
+        };
+    }, [eventName, element, options]);
+}
+export default useEventListener;

package/dist/hooks/useForceUpdate.d.ts

@@ -0,0 +1,5 @@
+export default function useForceUpdate(): [
+    () => void,
+    Record<PropertyKey, never>
+];
+//# sourceMappingURL=useForceUpdate.d.ts.map

package/dist/hooks/useForceUpdate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useForceUpdate.d.ts","sourceRoot":"","sources":["../../lib/hooks/useForceUpdate.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,OAAO,UAAU,cAAc,IAAI;IACxC,MAAM,IAAI;IACV,MAAM,CAAC,WAAW,EAAE,KAAK,CAAC;CAC3B,CAGA"}

package/dist/hooks/useForceUpdate.js

@@ -0,0 +1,5 @@
+import { useReducer } from 'react';
+export default function useForceUpdate() {
+    const [value, forceUpdate] = useReducer(() => ({}), {});
+    return [forceUpdate, value];
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { default as useDerivedState } from './hooks/useDerivedState';
+export { default as useEventListener } from './hooks/useEventListener';
+export { default as useForceUpdate } from './hooks/useForceUpdate';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACvE,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { default as useDerivedState } from './hooks/useDerivedState';
+export { default as useEventListener } from './hooks/useEventListener';
+export { default as useForceUpdate } from './hooks/useForceUpdate';

package/dist/utils/index.d.ts

@@ -0,0 +1,4 @@
+import type { DependencyList } from 'react';
+export declare function isFunction(input: unknown): input is Function;
+export declare function depsAreEqual(prevDeps: DependencyList, deps: DependencyList): boolean;
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AAG5C,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D;AAED,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,cAAc,EACxB,IAAI,EAAE,cAAc,GACnB,OAAO,CAKT"}

package/dist/utils/index.js

@@ -0,0 +1,8 @@
+// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+export function isFunction(input) {
+    return typeof input === 'function';
+}
+export function depsAreEqual(prevDeps, deps) {
+    return (prevDeps.length === deps.length &&
+        deps.every((dep, index) => Object.is(dep, prevDeps[index])));
+}

package/lib/hooks/useDerivedState.ts

@@ -0,0 +1,108 @@
+/**
+ * @file Based on {@link https://github.com/peterjuras/use-state-with-deps}
+ *
+ * @license MIT
+ *
+ * Copyright (c) 2020 Peter Juras
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import {
+  useCallback,
+  useRef,
+  type DependencyList,
+  type Dispatch,
+  type SetStateAction,
+} from 'react';
+import { depsAreEqual, isFunction } from '../utils';
+import useForceUpdate from './useForceUpdate';
+
+/**
+ * `useState` hook with an additional dependency array that resets
+ * the state to the `initialState` param when the dependencies passed
+ * in the `deps` array change.
+ *
+ * @param initialState
+ * The state that will be set when the component mounts or the
+ * dependencies change.
+ *
+ * It can also be a function which resolves to the state. If the state
+ * is reset due to a change of dependencies, this function will be called with the previous
+ * state (`undefined` for the first call upon mount).
+ * @param deps Dependencies for this hook that resets the state to `initialState`
+ */
+export default function useDerivedState<S>(
+  initialState: S | ((previousState?: S) => S),
+  deps: DependencyList,
+): [S, Dispatch<SetStateAction<S>>] {
+  const isMounted = useRef(false);
+
+  // Determine initial state
+  let usableInitialState: S | null = null;
+  if (!isMounted.current) {
+    isMounted.current = true;
+    if (isFunction(initialState)) {
+      usableInitialState = initialState();
+    } else {
+      usableInitialState = initialState;
+    }
+  }
+
+  // It would be possible to use useState instead of
+  // useRef to store the state, however this would
+  // trigger re-renders whenever the state is reset due
+  // to a change in dependencies. In order to avoid these
+  // re-renders, the state is stored in a ref and an
+  // update is triggered via forceUpdate below when necessary
+  const state = useRef(usableInitialState as S);
+
+  // Check if dependencies have changed
+  const prevDeps = useRef(deps);
+  if (!depsAreEqual(prevDeps.current, deps)) {
+    // Update state and deps
+    let nextState: S;
+    if (isFunction(initialState)) {
+      nextState = initialState(state.current);
+    } else {
+      nextState = initialState;
+    }
+    state.current = nextState;
+    prevDeps.current = deps;
+  }
+
+  const [forceUpdate] = useForceUpdate();
+
+  const updateState = useCallback(function updateState(
+    newState: S | ((previousState: S) => S),
+  ): void {
+    let nextState: S;
+    if (isFunction(newState)) {
+      nextState = newState(state.current);
+    } else {
+      nextState = newState;
+    }
+    if (!Object.is(state.current, nextState)) {
+      state.current = nextState;
+      forceUpdate();
+    }
+  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+
+  return [state.current, updateState];
+}

package/lib/hooks/useEventListener.ts

@@ -0,0 +1,106 @@
+/**
+ * @file Based on {@link https://github.com/juliencrn/usehooks-ts}
+ *
+ * @license MIT
+ *
+ * Copyright (c) 2020 Julien CARON
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { useEffect, useLayoutEffect, useRef } from 'react';
+
+/**
+ * Adds `handler` as a listener for the event `eventName` of `element`
+ * (or `window` by default) with the provided `options` applied.
+ *
+ * It is the user's responsibility to make sure `element` and `options` values
+ * are correctly memoized!
+ */
+
+// SVGElement Event based useEventListener interface
+function useEventListener<
+  K extends keyof SVGElementEventMap,
+  T extends SVGElement,
+>(
+  eventName: K,
+  handler: (event: SVGElementEventMap[K]) => void,
+  element: T,
+  options?: boolean | AddEventListenerOptions,
+): void;
+
+// HTMLElement Event based useEventListener interface
+function useEventListener<
+  K extends keyof HTMLElementEventMap,
+  T extends HTMLElement,
+>(
+  eventName: K,
+  handler: (event: HTMLElementEventMap[K]) => void,
+  element: T,
+  options?: boolean | AddEventListenerOptions,
+): void;
+
+// Document Event based useEventListener interface
+function useEventListener<K extends keyof DocumentEventMap>(
+  eventName: K,
+  handler: (event: DocumentEventMap[K]) => void,
+  element: Document,
+  options?: boolean | AddEventListenerOptions,
+): void;
+
+// Window Event based useEventListener interface
+function useEventListener<K extends keyof WindowEventMap>(
+  eventName: K,
+  handler: (event: WindowEventMap[K]) => void,
+  element?: Window,
+  options?: boolean | AddEventListenerOptions,
+): void;
+
+function useEventListener(
+  eventName: string,
+  handler: (event: Event) => void,
+  element?: EventTarget,
+  options?: boolean | AddEventListenerOptions,
+) {
+  // Create a ref that stores handler
+  const savedHandler = useRef(handler);
+
+  useLayoutEffect(() => {
+    savedHandler.current = handler;
+  }, [handler]);
+
+  useEffect(() => {
+    // Define the listening target
+    const targetElement = element ?? window;
+
+    // Create event listener that calls handler function stored in ref
+    const listener: typeof handler = (event) => {
+      savedHandler.current(event);
+    };
+
+    targetElement.addEventListener(eventName, listener, options);
+
+    // Remove event listener on cleanup
+    return () => {
+      targetElement.removeEventListener(eventName, listener, options);
+    };
+  }, [eventName, element, options]);
+}
+
+export default useEventListener;

package/lib/hooks/useForceUpdate.ts

@@ -0,0 +1,9 @@
+import { useReducer } from 'react';
+
+export default function useForceUpdate(): [
+  () => void,
+  Record<PropertyKey, never>,
+] {
+  const [value, forceUpdate] = useReducer(() => ({}), {});
+  return [forceUpdate, value];
+}

package/lib/index.ts

@@ -0,0 +1,3 @@
+export { default as useDerivedState } from './hooks/useDerivedState';
+export { default as useEventListener } from './hooks/useEventListener';
+export { default as useForceUpdate } from './hooks/useForceUpdate';

package/lib/utils/index.ts

@@ -0,0 +1,16 @@
+import type { DependencyList } from 'react';
+
+// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+export function isFunction(input: unknown): input is Function {
+  return typeof input === 'function';
+}
+
+export function depsAreEqual(
+  prevDeps: DependencyList,
+  deps: DependencyList,
+): boolean {
+  return (
+    prevDeps.length === deps.length &&
+    deps.every((dep, index) => Object.is(dep, prevDeps[index]))
+  );
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@aweebit/react-essentials",
+  "version": "0.4.0",
+  "type": "module",
+  "repository": "github:aweebit/react-essentials",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "prettier:base": "prettier --write",
+    "prettier": "npm run prettier:base -- .",
+    "lint": "eslint --max-warnings=0",
+    "build": "rimraf dist && tsc -b -f",
+    "prepare": "husky && npm run build"
+  },
+  "lint-staged": {
+    "!(*.{jsx,jsx,ts,tsx})": "npm run prettier -- --ignore-unknown",
+    "**.{jsx,jsx,ts,tsx}": "npm run lint --"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0 <20"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.28.0",
+    "@types/react": "^19.1.6",
+    "eslint": "^9.28.0",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.1.0",
+    "prettier": "3.5.3",
+    "rimraf": "^6.0.1",
+    "typescript": "~5.8.3",
+    "typescript-eslint": "^8.33.0"
+  },
+  "license": "MIT"
+}