@aweebit/react-essentials 0.5.4 → 0.6.0

package/dist/hooks/useStateWithDeps.d.ts

@@ -6,18 +6,17 @@
  */
 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
+ * `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
+ * @param initialState The value to which the state is set when the component is
+ * mounted or dependencies change
  *
- * It can also be a function which returns a state value. If the state is reset
+ * 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<S>(initialState: S | ((previousState?: S) => S), deps: DependencyList): [S, Dispatch<SetStateAction<S>>];
+export declare function useStateWithDeps<S>(initialState: S | ((previousState?: S) => S), deps: DependencyList): [S, Dispatch<SetStateAction<S>>];
 //# sourceMappingURL=useStateWithDeps.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"useStateWithDeps.d.ts","sourceRoot":"","sources":["../../lib/hooks/useStateWithDeps.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,cAAc,EACpB,MAAM,OAAO,CAAC;AAIf;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,OAAO,UAAU,gBAAgB,CAAC,CAAC,EACxC,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,CA4ClC"}
+{"version":3,"file":"useStateWithDeps.d.ts","sourceRoot":"","sources":["../../src/hooks/useStateWithDeps.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,cAAc,EACpB,MAAM,OAAO,CAAC;AAIf;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,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,CA4ClC"}

package/dist/hooks/useStateWithDeps.js

@@ -5,23 +5,22 @@
  * @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
+ * @param initialState The value to which the state is set when the component is
+ * mounted or dependencies change
  *
- * It can also be a function which returns a state value. If the state is reset
+ * 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) {
+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

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;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,gBAAgB,CAC9B,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"}

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,52 @@
+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;
+};
+/**
+ * @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
+ *
+ * @example
+ * ```tsx
+ * const { ItemsContext, useItems } = createSafeContext<string[]>()('Items');
+ *
+ * const Parent = () => (
+ *   <ItemsContext value={['compass', 'newspaper', 'banana']}>
+ *     <Child />
+ *   </ItemsContext>
+ * );
+ *
+ * const Child = () => useItems().join(', ');
+ * ```
+ *
+ * @returns
+ * A function that accepts a single string argument `displayName` (e.g.
+ * `"Items"`) and returns an object with the following properties:
+ * - ``` `${displayName}Context` ``` (e.g. `ItemsContext`): the context
+ * - ``` `use${displayName}` ``` (e.g. `useItems`): 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;;GAEG;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;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;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,46 @@
+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
+ *
+ * @example
+ * ```tsx
+ * const { ItemsContext, useItems } = createSafeContext<string[]>()('Items');
+ *
+ * const Parent = () => (
+ *   <ItemsContext value={['compass', 'newspaper', 'banana']}>
+ *     <Child />
+ *   </ItemsContext>
+ * );
+ *
+ * const Child = () => useItems().join(', ');
+ * ```
+ *
+ * @returns
+ * A function that accepts a single string argument `displayName` (e.g.
+ * `"Items"`) and returns an object with the following properties:
+ * - ``` `${displayName}Context` ``` (e.g. `ItemsContext`): the context
+ * - ``` `use${displayName}` ``` (e.g. `useItems`): 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;AA2BxC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;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.6.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,170 @@
+/**
+ * @file Based on {@link https://github.com/juliencrn/usehooks-ts}
+ *
+ * @license MIT
+ * @copyright 2020 Julien CARON
+ */
+
+import { useEffect, useMemo, useRef } from 'react';
+
+/**
+ * Adds `handler` as a listener for the event `eventName` of `element` with the
+ * provided `options` applied
+ *
+ * If `element` is `undefined`, `window` is used instead.
+ *
+ * If `element` is `null`, no event listener is added.
+ *
+ * @example
+ * ```tsx
+ * useEventListener('resize', () => {
+ *   console.log(window.innerWidth, window.innerHeight);
+ * });
+ *
+ * useEventListener(
+ *   'visibilitychange',
+ *   () => console.log(document.visibilityState),
+ *   document
+ * );
+ *
+ * const buttonRef = useRef<HTMLButtonElement>(null);
+ * useEventListener("click", () => console.log("click"), buttonRef.current);
+ * ```
+ *
+ * @ignore
+ */
+export function useEventListener<
+  K extends keyof HTMLElementEventMap,
+  T extends HTMLElement,
+>(
+  eventName: K,
+  handler: (this: NoInfer<T>, event: HTMLElementEventMap[K]) => void,
+  element: T | null,
+  options?: boolean | AddEventListenerOptions,
+): void;
+
+/**
+ * @see {@linkcode useEventListener}
+ * @ignore
+ */
+export function useEventListener<
+  K extends keyof SVGElementEventMap,
+  T extends SVGElement,
+>(
+  eventName: K,
+  handler: (this: NoInfer<T>, event: SVGElementEventMap[K]) => void,
+  element: T | null,
+  options?: boolean | AddEventListenerOptions,
+): void;
+
+/**
+ * @see {@linkcode useEventListener}
+ * @ignore
+ */
+export function useEventListener<
+  K extends keyof MathMLElementEventMap,
+  T extends MathMLElement,
+>(
+  eventName: K,
+  handler: (this: NoInfer<T>, event: MathMLElementEventMap[K]) => void,
+  element: T | null,
+  options?: boolean | AddEventListenerOptions,
+): void;
+
+/**
+ * @see {@linkcode useEventListener}
+ * @ignore
+ */
+export function useEventListener<K extends keyof DocumentEventMap>(
+  eventName: K,
+  handler: (this: Document, event: DocumentEventMap[K]) => void,
+  element: Document,
+  options?: boolean | AddEventListenerOptions,
+): void;
+
+/**
+ * @see {@linkcode useEventListener}
+ * @ignore
+ */
+export function useEventListener<K extends keyof WindowEventMap>(
+  eventName: K,
+  handler: (this: Window, event: WindowEventMap[K]) => void,
+  element?: Window,
+  options?: boolean | AddEventListenerOptions,
+): void;
+
+/**
+ * Adds `handler` as a listener for the event `eventName` of `element` with the
+ * provided `options` applied
+ *
+ * If `element` is `undefined`, `window` is used instead.
+ *
+ * If `element` is `null`, no event listener is added.
+ *
+ * @example
+ * ```tsx
+ * useEventListener('resize', () => {
+ *   console.log(window.innerWidth, window.innerHeight);
+ * });
+ *
+ * useEventListener(
+ *   'visibilitychange',
+ *   () => console.log(document.visibilityState),
+ *   document
+ * );
+ *
+ * const buttonRef = useRef<HTMLButtonElement>(null);
+ * useEventListener("click", () => console.log("click"), buttonRef.current);
+ * ```
+ */
+export function useEventListener<T extends EventTarget>(
+  eventName: string,
+  handler: (this: NoInfer<T>, event: Event) => void,
+  element?: T | null,
+  options?: boolean | AddEventListenerOptions,
+): void;
+
+export function useEventListener(
+  eventName: string,
+  handler: (this: EventTarget, event: Event) => void,
+  element?: EventTarget | null,
+  options?: boolean | AddEventListenerOptions,
+) {
+  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 (element === null) {
+      // No element has been attached to the ref yet
+      return;
+    }
+
+    // Define the listening target
+    const targetElement = element ?? window;
+
+    // Create event listener that calls handler function stored in ref
+    const listener: typeof handler = function (event) {
+      handlerRef.current.call(this, event);
+    };
+
+    targetElement.addEventListener(eventName, listener, memoizedOptions);
+
+    // Remove event listener on cleanup
+    return () => {
+      targetElement.removeEventListener(eventName, listener, memoizedOptions);
+    };
+  }, [eventName, element, memoizedOptions]);
+}

package/{lib → src}/hooks/useForceUpdate.ts

@@ -1,5 +1,10 @@
 import { useReducer, useRef } from 'react';
 
+/* eslint-disable */
+import type { useStateWithDeps } from './useStateWithDeps.js';
+import type { useReducerWithDeps } from './useReducerWithDeps.js';
+/* eslint-enable */
+
 /**
  * Enables you to imperatively trigger re-rendering of components
  *
@@ -12,9 +17,8 @@ import { useReducer, useRef } from 'react';
  * Can be used for conditionally calling state setters when state needs to be
  * reset. That is legal and better than using effects (see
  * {@link https://react.dev/learn/-might-not-need-an-effect#adjusting-some-state-when-a-prop-changes You Might Not Need an Effect > Adjusting some state when a prop changes}),
- * but can often be avoided by using
- * [`useStateWithDeps`]({@link ./useStateWithDeps.ts}) or
- * [`useReducerWithDeps`]({@link ./useReducerWithDeps.ts}).
+ * but can often be avoided by using {@linkcode useStateWithDeps} or
+ * {@linkcode useReducerWithDeps}.
  *
  * Important: the callback function is called once per render, not once per
  * `forceUpdate` call! If React batches `forceUpdate` calls, then it will only
@@ -25,9 +29,7 @@ import { useReducer, useRef } from 'react';
  * 1. A `forceUpdate` function that triggers a re-render
  * 2. The number of times `forceUpdate` has been called so far
  */
-export default function useForceUpdate(
-  callback?: () => void,
-): [() => void, bigint] {
+export function useForceUpdate(callback?: () => void): [() => void, bigint] {
   // It is very unlikely that the number of updates will exceed
   // Number.MAX_SAFE_INTEGER, but not impossible. That is why we use bigints.
   const [counter, forceUpdate] = useReducer((prev) => prev + 1n, 0n);

package/{lib → src}/hooks/useReducerWithDeps.ts

@@ -1,16 +1,22 @@
-import {
-  type ActionDispatch,
-  type AnyActionArg,
-  type DependencyList,
-  useCallback,
-  useRef,
-} from 'react';
-import useStateWithDeps from './useStateWithDeps.js';
+import { type DependencyList, useCallback, useRef } from 'react';
+import { useStateWithDeps } from './useStateWithDeps.js';
+
+// We cannot simply import the following types from @types/react since they are
+// only available starting from React 19, but we also want to support React 18
+// whose type declarations for useReducer are very different.
+
+/** @ignore */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyActionArg = [] | [any];
+
+/** @ignore */
+export type ActionDispatch<ActionArg extends AnyActionArg> = (
+  ...args: ActionArg
+) => void;
 
 /**
- * `useReducer` hook with an additional dependency array that resets the state
- * to the `initialState` param when the dependencies passed in the `deps` array
- * change
+ * `useReducer` hook with an additional dependency array `deps` that resets the
+ * state to `initialState` when dependencies change
  *
  * ### On linter support
  *
@@ -19,7 +25,7 @@ import useStateWithDeps from './useStateWithDeps.js';
  * However, as we would like to keep the hook as compatible with `useReducer` as
  * possible, we don't want to artificially change the parameter's position.
  * Therefore, there will be no warnings about missing dependencies.
- * Because of that, addition caution is advised!
+ * Because of that, additional caution is advised!
  * Be sure to check no dependencies are missing from the `deps` array.
  *
  * Related issue: {@link https://github.com/facebook/react/issues/25443}.
@@ -27,20 +33,20 @@ import useStateWithDeps from './useStateWithDeps.js';
  * Unlike `eslint-plugin-react-hooks` maintained by React's team, the unofficial
  * `useExhaustiveDependencies` rule provided for Biome by Biome's team
  * does actually have support for dependency arrays at other positions, see
- * {@link https://biomejs.dev/linter/rules/use-exhaustive-dependencies/#validating-dependencies}.
+ * {@link https://biomejs.dev/linter/rules/use-exhaustive-dependencies/#validating-dependencies useExhaustiveDependencies > Options > Validating dependencies}.
  *
  * @param reducer The reducer function that specifies how the state gets updated
  *
- * @param initialState The state that will be set when the component mounts or
- * the dependencies change
+ * @param initialState The value to which the state is set when the component is
+ * mounted or dependencies change
  *
- * It can also be a function which returns a state value. If the state is reset
+ * 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 useReducerWithDeps<S, A extends AnyActionArg>(
+export function useReducerWithDeps<S, A extends AnyActionArg>(
   reducer: (prevState: S, ...args: A) => S,
   initialState: S | ((previousState?: S) => S),
   deps: DependencyList,

package/{lib → src}/hooks/useStateWithDeps.ts

@@ -12,24 +12,23 @@ import {
   type Dispatch,
   type SetStateAction,
 } 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
+ * @param initialState The value to which the state is set when the component is
+ * mounted or dependencies change
  *
- * It can also be a function which returns a state value. If the state is reset
+ * 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<S>(
+export function useStateWithDeps<S>(
   initialState: S | ((previousState?: S) => S),
   deps: DependencyList,
 ): [S, Dispatch<SetStateAction<S>>] {

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './hooks/index.js';
+export * from './misc/index.js';