@aweebit/react-essentials 0.5.4 → 0.7.0

package/dist/hooks/useStateWithDeps.js

@@ -5,29 +5,61 @@
  * @copyright 2020 Peter Juras
  */
 import { useCallback, useRef, } from 'react';
-import { depsAreEqual, isFunction } from '../utils/index.js';
-import useForceUpdate from './useForceUpdate.js';
+import { depsAreEqual, isFunction } from '../utils.js';
+import { useForceUpdate } from './useForceUpdate.js';
 /**
- * `useState` hook with an additional dependency array that resets the state
- * to the `initialState` param when the dependencies passed in the `deps` array
- * change
+ * `useState` hook with an additional dependency array `deps` that resets the
+ * state to `initialState` when dependencies change
  *
- * @param initialState The state that will be set when the component mounts or
- * the dependencies change
+ * For motivation and more examples, see
+ * https://github.com/facebook/react/issues/33041.
  *
- * It can also be a function which returns a state value. If the state is reset
+ * @example
+ * ```tsx
+ * type Activity = 'breakfast' | 'exercise' | 'swim' | 'board games' | 'dinner';
+ *
+ * const timeOfDayOptions = ['morning', 'afternoon', 'evening'] as const;
+ * type TimeOfDay = (typeof timeOfDayOptions)[number];
+ *
+ * const activityOptionsByTimeOfDay: {
+ *   [K in TimeOfDay]: [Activity, ...Activity[]];
+ * } = {
+ *   morning: ['breakfast', 'exercise', 'swim'],
+ *   afternoon: ['exercise', 'swim', 'board games'],
+ *   evening: ['board games', 'dinner'],
+ * };
+ *
+ * export function Example() {
+ *   const [timeOfDay, setTimeOfDay] = useState<TimeOfDay>('morning');
+ *
+ *   const activityOptions = activityOptionsByTimeOfDay[timeOfDay];
+ *   const [activity, setActivity] = useStateWithDeps<Activity>(
+ *     (prev) => {
+ *       // Make sure activity is always valid for the current timeOfDay value,
+ *       // but also don't reset it unless necessary:
+ *       return prev && activityOptions.includes(prev) ? prev : activityOptions[0];
+ *     },
+ *     [activityOptions],
+ *   );
+ *
+ *   return '...';
+ * }
+ * ```
+ *
+ * @param initialState The value to which the state is set when the component is
+ * mounted or dependencies change
+ *
+ * It can also be a function that returns a state value. If the state is reset
  * due to a change of dependencies, this function will be passed the previous
  * state as its argument (will be `undefined` in the first call upon mount).
  *
  * @param deps Dependencies that reset the state to `initialState`
  */
-export default function useStateWithDeps(initialState, deps) {
-    // 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
+export function useStateWithDeps(initialState, deps) {
+    // 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 updates are triggered with forceUpdate when necessary.
     const state = useRef(undefined);
     const prevDeps = useRef(deps);
     const isMounted = useRef(false);

package/dist/hooks/useStateWithDeps.js.map

@@ -1 +1 @@
-{"version":3,"file":"useStateWithDeps.js","sourceRoot":"","sources":["../../lib/hooks/useStateWithDeps.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,WAAW,EACX,MAAM,GAIP,MAAM,OAAO,CAAC;AACf,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,cAAc,MAAM,qBAAqB,CAAC;AAEjD;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,OAAO,UAAU,gBAAgB,CACtC,YAA4C,EAC5C,IAAoB;IAEpB,kDAAkD;IAClD,gDAAgD;IAChD,qDAAqD;IACrD,uDAAuD;IACvD,kDAAkD;IAClD,2DAA2D;IAC3D,MAAM,KAAK,GAAG,MAAM,CAAC,SAAc,CAAC,CAAC;IAErC,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAC9B,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAEhC,mEAAmE;IACnE,IAAI,CAAC,SAAS,CAAC,OAAO,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,CAAC;QAChE,wBAAwB;QACxB,IAAI,SAAY,CAAC;QACjB,IAAI,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;YAC7B,SAAS,GAAG,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC1C,CAAC;aAAM,CAAC;YACN,SAAS,GAAG,YAAY,CAAC;QAC3B,CAAC;QACD,KAAK,CAAC,OAAO,GAAG,SAAS,CAAC;QAC1B,QAAQ,CAAC,OAAO,GAAG,IAAI,CAAC;QACxB,SAAS,CAAC,OAAO,GAAG,IAAI,CAAC;IAC3B,CAAC;IAED,MAAM,CAAC,WAAW,CAAC,GAAG,cAAc,EAAE,CAAC;IAEvC,MAAM,WAAW,GAAG,WAAW,CAAC,SAAS,WAAW,CAClD,QAAuC;QAEvC,IAAI,SAAY,CAAC;QACjB,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YACzB,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACtC,CAAC;aAAM,CAAC;YACN,SAAS,GAAG,QAAQ,CAAC;QACvB,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,CAAC;YACzC,KAAK,CAAC,OAAO,GAAG,SAAS,CAAC;YAC1B,WAAW,EAAE,CAAC;QAChB,CAAC;IACH,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,kDAAkD;IAE1D,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;AACtC,CAAC"}
+{"version":3,"file":"useStateWithDeps.js","sourceRoot":"","sources":["../../src/hooks/useStateWithDeps.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,WAAW,EACX,MAAM,GAIP,MAAM,OAAO,CAAC;AACf,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,MAAM,UAAU,gBAAgB,CAC9B,YAA4C,EAC5C,IAAoB;IAEpB,6EAA6E;IAC7E,6EAA6E;IAC7E,2EAA2E;IAC3E,8EAA8E;IAC9E,MAAM,KAAK,GAAG,MAAM,CAAC,SAAc,CAAC,CAAC;IAErC,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAC9B,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAEhC,mEAAmE;IACnE,IAAI,CAAC,SAAS,CAAC,OAAO,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,CAAC;QAChE,wBAAwB;QACxB,IAAI,SAAY,CAAC;QACjB,IAAI,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;YAC7B,SAAS,GAAG,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC1C,CAAC;aAAM,CAAC;YACN,SAAS,GAAG,YAAY,CAAC;QAC3B,CAAC;QACD,KAAK,CAAC,OAAO,GAAG,SAAS,CAAC;QAC1B,QAAQ,CAAC,OAAO,GAAG,IAAI,CAAC;QACxB,SAAS,CAAC,OAAO,GAAG,IAAI,CAAC;IAC3B,CAAC;IAED,MAAM,CAAC,WAAW,CAAC,GAAG,cAAc,EAAE,CAAC;IAEvC,MAAM,WAAW,GAAG,WAAW,CAAC,SAAS,WAAW,CAClD,QAAuC;QAEvC,IAAI,SAAY,CAAC;QACjB,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YACzB,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACtC,CAAC;aAAM,CAAC;YACN,SAAS,GAAG,QAAQ,CAAC;QACvB,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,CAAC;YACzC,KAAK,CAAC,OAAO,GAAG,SAAS,CAAC;YAC1B,WAAW,EAAE,CAAC;QAChB,CAAC;IACH,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,kDAAkD;IAE1D,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;AACtC,CAAC"}

package/dist/index.d.ts

@@ -1,6 +1,3 @@
-export { default as useEventListener } from './hooks/useEventListener.js';
-export { default as useForceUpdate } from './hooks/useForceUpdate.js';
-export { default as useIsomorphicLayoutEffect } from './hooks/useIsomorphicLayoutEffect.js';
-export { default as useReducerWithDeps } from './hooks/useReducerWithDeps.js';
-export { default as useStateWithDeps } from './hooks/useStateWithDeps.js';
+export * from './hooks/index.js';
+export * from './misc/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC1E,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,EAAE,OAAO,IAAI,yBAAyB,EAAE,MAAM,sCAAsC,CAAC;AAC5F,OAAO,EAAE,OAAO,IAAI,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAC9E,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,6BAA6B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC"}

package/dist/index.js

@@ -1,6 +1,3 @@
-export { default as useEventListener } from './hooks/useEventListener.js';
-export { default as useForceUpdate } from './hooks/useForceUpdate.js';
-export { default as useIsomorphicLayoutEffect } from './hooks/useIsomorphicLayoutEffect.js';
-export { default as useReducerWithDeps } from './hooks/useReducerWithDeps.js';
-export { default as useStateWithDeps } from './hooks/useStateWithDeps.js';
+export * from './hooks/index.js';
+export * from './misc/index.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC1E,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,EAAE,OAAO,IAAI,yBAAyB,EAAE,MAAM,sCAAsC,CAAC;AAC5F,OAAO,EAAE,OAAO,IAAI,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAC9E,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,6BAA6B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC"}

package/dist/misc/createSafeContext.d.ts

@@ -0,0 +1,85 @@
+import { type Context, type Provider } from 'react';
+import type { ArgumentFallback } from '../utils.js';
+/**
+ * A React context with a required `displayName` and the obsolete `Consumer`
+ * property purposefully omitted so that it is impossible to pass the context
+ * as an argument to `useContext` or `use` (the hook produced with
+ * {@linkcode createSafeContext} should be used instead)
+ *
+ * @see {@linkcode createSafeContext}
+ */
+export type RestrictedContext<T> = Context<T> extends Provider<T> ? {
+    Provider: Provider<T>;
+    displayName: string;
+} & Provider<T> : {
+    Provider: Provider<T>;
+    displayName: string;
+};
+/**
+ * The return type of {@linkcode createSafeContext}
+ *
+ * @see {@linkcode createSafeContext}
+ */
+export type SafeContext<DisplayName extends string, T> = {
+    [K in `${DisplayName}Context`]: RestrictedContext<T>;
+} & {
+    [K in `use${DisplayName}`]: () => T;
+};
+/**
+ * For a given type `T`, returns a function that produces both a context of that
+ * type and a hook that returns the current context value if one was provided,
+ * or throws an error otherwise
+ *
+ * The advantages over vanilla `createContext` are that no default value has to
+ * be provided, and that a meaningful context name is displayed in dev tools
+ * instead of generic `Context.Provider`.
+ *
+ * @example
+ * ```tsx
+ * enum Direction {
+ *   Up,
+ *   Down,
+ *   Left,
+ *   Right,
+ * }
+ *
+ * // Before
+ * const DirectionContext = createContext<Direction | undefined>(undefined);
+ * DirectionContext.displayName = 'DirectionContext';
+ *
+ * const useDirection = () => {
+ *   const direction = useContext(DirectionContext);
+ *   if (direction === undefined) {
+ *     // Called outside of a <DirectionContext.Provider> boundary!
+ *     // Or maybe undefined was explicitly provided as the context value
+ *     // (ideally that shouldn't be allowed, but it is because we had to include
+ *     // undefined in the context type so as to provide a meaningful default)
+ *     throw new Error('No DirectionContext value was provided');
+ *   }
+ *   // Thanks to the undefined check, the type is now narrowed down to Direction
+ *   return direction;
+ * };
+ *
+ * // After
+ * const { DirectionContext, useDirection } =
+ *   createSafeContext<Direction>()('Direction'); // That's it :)
+ *
+ * const Parent = () => (
+ *   // Providing undefined as the value is not allowed 👍
+ *   <Direction.Provider value={Direction.Up}>
+ *     <Child />
+ *   </Direction.Provider>
+ * );
+ *
+ * const Child = () => `Current direction: ${Direction[useDirection()]}`;
+ * ```
+ *
+ * @returns
+ * A function that accepts a single string argument `displayName` (e.g.
+ * `"Direction"`) and returns an object with the following properties:
+ * - ``` `${displayName}Context` ``` (e.g. `DirectionContext`): the context
+ * - ``` `use${displayName}` ``` (e.g. `useDirection`): a hook that returns the
+ *   current context value if one was provided, or throws an error otherwise
+ */
+export declare function createSafeContext<T = never>(): <DisplayName extends string>(displayName: [T] extends [never] ? never : ArgumentFallback<DisplayName, never, string>) => SafeContext<DisplayName, T>;
+//# sourceMappingURL=createSafeContext.d.ts.map

package/dist/misc/createSafeContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createSafeContext.d.ts","sourceRoot":"","sources":["../../src/misc/createSafeContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,QAAQ,EAA6B,MAAM,OAAO,CAAC;AAC/E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAIpD;;;;;;;GAOG;AAIH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAC7B,OAAO,CAAC,CAAC,CAAC,SAAS,QAAQ,CAAC,CAAC,CAAC,GAC1B;IAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,QAAQ,CAAC,CAAC,CAAC,GAC5D;IAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC;AAErD;;;;GAIG;AACH,MAAM,MAAM,WAAW,CAAC,WAAW,SAAS,MAAM,EAAE,CAAC,IAAI;KACtD,CAAC,IAAI,GAAG,WAAW,SAAS,GAAG,iBAAiB,CAAC,CAAC,CAAC;CACrD,GAAG;KACD,CAAC,IAAI,MAAM,WAAW,EAAE,GAAG,MAAM,CAAC;CACpC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,GAAG,KAAK,MACjC,WAAW,SAAS,MAAM,EAChC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAC5B,KAAK,GACL,gBAAgB,CAAC,WAAW,EAAE,KAAK,EAAE,MAAM,CAAC,KAC/C,WAAW,CAAC,WAAW,EAAE,CAAC,CAAC,CAsB/B"}

package/dist/misc/createSafeContext.js

@@ -0,0 +1,77 @@
+import { createContext, useContext } from 'react';
+const moValueSymbol = Symbol('noValue');
+/**
+ * For a given type `T`, returns a function that produces both a context of that
+ * type and a hook that returns the current context value if one was provided,
+ * or throws an error otherwise
+ *
+ * The advantages over vanilla `createContext` are that no default value has to
+ * be provided, and that a meaningful context name is displayed in dev tools
+ * instead of generic `Context.Provider`.
+ *
+ * @example
+ * ```tsx
+ * enum Direction {
+ *   Up,
+ *   Down,
+ *   Left,
+ *   Right,
+ * }
+ *
+ * // Before
+ * const DirectionContext = createContext<Direction | undefined>(undefined);
+ * DirectionContext.displayName = 'DirectionContext';
+ *
+ * const useDirection = () => {
+ *   const direction = useContext(DirectionContext);
+ *   if (direction === undefined) {
+ *     // Called outside of a <DirectionContext.Provider> boundary!
+ *     // Or maybe undefined was explicitly provided as the context value
+ *     // (ideally that shouldn't be allowed, but it is because we had to include
+ *     // undefined in the context type so as to provide a meaningful default)
+ *     throw new Error('No DirectionContext value was provided');
+ *   }
+ *   // Thanks to the undefined check, the type is now narrowed down to Direction
+ *   return direction;
+ * };
+ *
+ * // After
+ * const { DirectionContext, useDirection } =
+ *   createSafeContext<Direction>()('Direction'); // That's it :)
+ *
+ * const Parent = () => (
+ *   // Providing undefined as the value is not allowed 👍
+ *   <Direction.Provider value={Direction.Up}>
+ *     <Child />
+ *   </Direction.Provider>
+ * );
+ *
+ * const Child = () => `Current direction: ${Direction[useDirection()]}`;
+ * ```
+ *
+ * @returns
+ * A function that accepts a single string argument `displayName` (e.g.
+ * `"Direction"`) and returns an object with the following properties:
+ * - ``` `${displayName}Context` ``` (e.g. `DirectionContext`): the context
+ * - ``` `use${displayName}` ``` (e.g. `useDirection`): a hook that returns the
+ *   current context value if one was provided, or throws an error otherwise
+ */
+export function createSafeContext() {
+    return (displayName) => {
+        const contextName = `${displayName}Context`;
+        const hookName = `use${displayName}`;
+        const Context = createContext(moValueSymbol);
+        Context.displayName = contextName;
+        return {
+            [contextName]: Context,
+            [hookName]: () => {
+                const value = useContext(Context);
+                if (value === moValueSymbol) {
+                    throw new Error(`No ${contextName} value was provided`);
+                }
+                return value;
+            },
+        };
+    };
+}
+//# sourceMappingURL=createSafeContext.js.map

package/dist/misc/createSafeContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createSafeContext.js","sourceRoot":"","sources":["../../src/misc/createSafeContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+B,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAG/E,MAAM,aAAa,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;AA6BxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,CACL,WAEgD,EACnB,EAAE;QAC/B,MAAM,WAAW,GAAG,GAAG,WAA0B,SAAkB,CAAC;QACpE,MAAM,QAAQ,GAAG,MAAM,WAA0B,EAAW,CAAC;QAE7D,MAAM,OAAO,GAAG,aAAa,CAA2B,aAAa,CAAC,CAAC;QACvE,OAAO,CAAC,WAAW,GAAG,WAAW,CAAC;QAElC,OAAO;YACL,CAAC,WAAW,CAAC,EAAE,OAA+B;YAC9C,CAAC,QAAQ,CAAC,EAAE,GAAG,EAAE;gBACf,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;gBAClC,IAAI,KAAK,KAAK,aAAa,EAAE,CAAC;oBAC5B,MAAM,IAAI,KAAK,CAAC,MAAM,WAAW,qBAAqB,CAAC,CAAC;gBAC1D,CAAC;gBACD,OAAO,KAAK,CAAC;YACf,CAAC;SAKF,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC"}

package/dist/misc/index.d.ts

@@ -0,0 +1,2 @@
+export * from './createSafeContext.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/misc/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC"}

package/dist/misc/index.js

@@ -0,0 +1,2 @@
+export * from './createSafeContext.js';
+//# sourceMappingURL=index.js.map

package/dist/misc/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/misc/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC"}

package/dist/utils.d.ts

@@ -0,0 +1,7 @@
+import type { DependencyList } from 'react';
+export type Callable = (...args: never) => unknown;
+export type ArgumentFallback<T extends Base, Default extends Base, Base = unknown> = [T] extends [never] ? Default : [Base] extends [T] ? Default : T;
+export declare function noop(): void;
+export declare function isFunction(input: unknown): input is Callable;
+export declare function depsAreEqual(prevDeps: DependencyList, deps: DependencyList): boolean;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AAE5C,MAAM,MAAM,QAAQ,GAAG,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC;AAEnD,MAAM,MAAM,gBAAgB,CAC1B,CAAC,SAAS,IAAI,EACd,OAAO,SAAS,IAAI,EACpB,IAAI,GAAG,OAAO,IACZ,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,OAAO,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,OAAO,GAAG,CAAC,CAAC;AAErE,wBAAgB,IAAI,SAAK;AAEzB,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 → utils.js}

@@ -1,5 +1,4 @@
 export function noop() { }
-// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
 export function isFunction(input) {
     return typeof input === 'function';
 }
@@ -7,4 +6,4 @@ export function depsAreEqual(prevDeps, deps) {
     return (prevDeps.length === deps.length &&
         deps.every((dep, index) => Object.is(dep, prevDeps[index])));
 }
-//# sourceMappingURL=index.js.map
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAUA,MAAM,UAAU,IAAI,KAAI,CAAC;AAEzB,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,OAAO,KAAK,KAAK,UAAU,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,QAAwB,EACxB,IAAoB;IAEpB,OAAO,CACL,QAAQ,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM;QAC/B,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAC5D,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aweebit/react-essentials",
-  "version": "0.5.4",
+  "version": "0.7.0",
   "type": "module",
   "repository": "github:aweebit/react-essentials",
   "main": "dist/index.js",
@@ -10,28 +10,38 @@
     "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 --"
+    "doc": "rimraf README.md && typedoc",
+    "prepack": "npm run build && npm run doc",
+    "prepare": "husky"
   },
   "peerDependencies": {
-    "react": ">=18.0.0 <20"
+    "@types/react": ">=18",
+    "react": ">=18",
+    "typescript": ">=5.4"
   },
-  "dependencies": {
-    "@types/react": "19.1.6"
+  "peerDependenciesMeta": {
+    "@types/react": {
+      "optional": true
+    },
+    "typescript": {
+      "optional": true
+    }
   },
   "devDependencies": {
-    "@eslint/js": "^9.28.0",
-    "eslint": "^9.28.0",
+    "@eslint/js": "^9.36.0",
+    "@types/react": "^18.3.24",
+    "eslint": "^9.36.0",
+    "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-react-hooks": "^5.2.0",
     "husky": "^9.1.7",
-    "lint-staged": "^16.1.0",
-    "prettier": "3.5.3",
+    "lint-staged": "^16.1.6",
+    "prettier": "3.6.2",
+    "react": "^18.3.1",
     "rimraf": "^6.0.1",
-    "typescript": "~5.8.3",
-    "typescript-eslint": "^8.33.1"
+    "typedoc": "^0.28.13",
+    "typedoc-plugin-markdown": "^4.9.0",
+    "typescript": "~5.9.2",
+    "typescript-eslint": "^8.44.0"
   },
   "license": "MIT"
 }

package/src/hooks/index.ts

@@ -0,0 +1,4 @@
+export * from './useEventListener.js';
+export * from './useForceUpdate.js';
+export * from './useReducerWithDeps.js';
+export * from './useStateWithDeps.js';

package/src/hooks/useEventListener.ts

@@ -0,0 +1,201 @@
+/**
+ * @file Based on {@link https://github.com/juliencrn/usehooks-ts}
+ *
+ * @license MIT
+ * @copyright 2020 Julien CARON
+ */
+
+import { useEffect, useMemo, useRef } from 'react';
+
+type UseEventListenerOverloadArgs<
+  EventMap,
+  K extends keyof EventMap,
+  T extends EventTarget,
+> = [
+  target: T | null,
+  eventName: K,
+  handler: (this: NoInfer<T>, event: EventMap[K]) => void,
+  options?: AddEventListenerOptions | boolean,
+];
+
+/**
+ * Adds `handler` as a listener for the event `eventName` of `target` with the
+ * provided `options` applied
+ *
+ * If `target` is not provided, `window` is used instead.
+ *
+ * If `target` is `null`, no event listener is added. This is useful when
+ * working with DOM element refs, or when the event listener needs to be removed
+ * temporarily.
+ *
+ * @example
+ * ```tsx
+ * useEventListener('resize', () => {
+ *   console.log(window.innerWidth, window.innerHeight);
+ * });
+ *
+ * useEventListener(document, 'visibilitychange', () => {
+ *   console.log(document.visibilityState);
+ * });
+ *
+ * const buttonRef = useRef<HTMLButtonElement>(null);
+ * useEventListener(buttonRef.current, 'click', () => console.log('click'));
+ * ```
+ *
+ * @ignore
+ */
+export function useEventListener<K extends keyof WindowEventMap>(
+  eventName: K,
+  handler: (this: Window, event: WindowEventMap[K]) => void,
+  options?: AddEventListenerOptions | boolean,
+): void;
+
+/**
+ * @see {@linkcode useEventListener}
+ * @ignore
+ */
+export function useEventListener<K extends keyof WindowEventMap>(
+  ...args: UseEventListenerOverloadArgs<WindowEventMap, K, Window>
+): void;
+
+/**
+ * @see {@linkcode useEventListener}
+ * @ignore
+ */
+export function useEventListener<K extends keyof DocumentEventMap>(
+  ...args: UseEventListenerOverloadArgs<DocumentEventMap, K, Document>
+): void;
+
+/**
+ * @see {@linkcode useEventListener}
+ * @ignore
+ */
+export function useEventListener<
+  K extends keyof HTMLElementEventMap,
+  T extends HTMLElement,
+>(...args: UseEventListenerOverloadArgs<HTMLElementEventMap, K, T>): void;
+
+/**
+ * @see {@linkcode useEventListener}
+ * @ignore
+ */
+export function useEventListener<
+  K extends keyof SVGElementEventMap,
+  T extends SVGElement,
+>(...args: UseEventListenerOverloadArgs<SVGElementEventMap, K, T>): void;
+
+/**
+ * @see {@linkcode useEventListener}
+ * @ignore
+ */
+export function useEventListener<
+  K extends keyof MathMLElementEventMap,
+  T extends MathMLElement,
+>(...args: UseEventListenerOverloadArgs<MathMLElementEventMap, K, T>): void;
+
+/**
+ * @see {@linkcode useEventListener}
+ */
+export function useEventListener<K extends keyof WindowEventMap>(
+  eventName: K,
+  handler: (this: Window, event: WindowEventMap[K]) => void,
+  options?: AddEventListenerOptions | boolean,
+): void;
+
+/**
+ * @see {@linkcode useEventListener}
+ */
+export function useEventListener<T extends EventTarget>(
+  target: T | null,
+  eventName: string,
+  handler: (this: NoInfer<T>, event: Event) => void,
+  options?: AddEventListenerOptions | boolean,
+): void;
+
+/**
+ * Adds `handler` as a listener for the event `eventName` of `target` with the
+ * provided `options` applied
+ *
+ * If `target` is not provided, `window` is used instead.
+ *
+ * If `target` is `null`, no event listener is added. This is useful when
+ * working with DOM element refs, or when the event listener needs to be removed
+ * temporarily.
+ *
+ * @example
+ * ```tsx
+ * useEventListener('resize', () => {
+ *   console.log(window.innerWidth, window.innerHeight);
+ * });
+ *
+ * useEventListener(document, 'visibilitychange', () => {
+ *   console.log(document.visibilityState);
+ * });
+ *
+ * const buttonRef = useRef<HTMLButtonElement>(null);
+ * useEventListener(buttonRef.current, 'click', () => console.log('click'));
+ * ```
+ */
+export function useEventListener(
+  ...args: UseEventListenerArgsWithoutTarget | UseEventListenerArgsWithTarget
+) {
+  let eventName: string;
+  let handler: (this: EventTarget, event: Event) => void;
+  let target: EventTarget | null | undefined;
+  let options: AddEventListenerOptions | boolean | undefined;
+
+  if (typeof args[0] === 'string') {
+    [eventName, handler, options] = args as UseEventListenerArgsWithoutTarget;
+  } else {
+    [target, eventName, handler, options] =
+      args as UseEventListenerArgsWithTarget;
+  }
+
+  const handlerRef = useRef(handler);
+  handlerRef.current = handler;
+
+  const {
+    capture = false,
+    once = false,
+    passive,
+    signal,
+  } = typeof options === 'boolean' ? { capture: options } : (options ?? {});
+
+  const memoizedOptions = useMemo(
+    () => options,
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [capture, once, passive, signal],
+  );
+
+  useEffect(() => {
+    if (target === null) {
+      // No element has been attached to the ref yet
+      return;
+    }
+
+    const definedTarget = target ?? window;
+
+    const listener: typeof handler = function (event) {
+      handlerRef.current.call(this, event);
+    };
+
+    definedTarget.addEventListener(eventName, listener, memoizedOptions);
+
+    return () => {
+      definedTarget.removeEventListener(eventName, listener, memoizedOptions);
+    };
+  }, [eventName, target, memoizedOptions]);
+}
+
+type UseEventListenerArgsWithoutTarget = [
+  eventName: string,
+  handler: (event: Event) => void,
+  options?: AddEventListenerOptions | boolean | undefined,
+];
+
+type UseEventListenerArgsWithTarget = [
+  target: EventTarget | null,
+  eventName: string,
+  handler: (event: Event) => void,
+  options?: AddEventListenerOptions | boolean | undefined,
+];