@aweebit/react-essentials 0.7.0 → 0.8.1

package/README.md

@@ -2,19 +2,50 @@
 
 [![NPM Version](https://img.shields.io/npm/v/%40aweebit%2Freact-essentials)](https://www.npmjs.com/package/@aweebit/react-essentials)
 
+### Requirements
+
+- React ≥ 18
+- TypeScript ≥ 5.4
+
+### Functions
+
 - [useEventListener()](#useeventlistener)
 - [useForceUpdate()](#useforceupdate)
 - [useReducerWithDeps()](#usereducerwithdeps)
 - [useStateWithDeps()](#usestatewithdeps)
 - [createSafeContext()](#createsafecontext)
+
+### Types
+
+- [UseEventListener](#useeventlistener-1)
+- [UseEventListenerWithImplicitWindowTarget](#useeventlistenerwithimplicitwindowtarget)
+- [UseEventListenerWithExplicitTarget](#useeventlistenerwithexplicittarget)
+- [UseEventListenerWithAnyExplicitTarget](#useeventlistenerwithanyexplicittarget)
+- [UseEventListenerWithImplicitWindowTargetArgs](#useeventlistenerwithimplicitwindowtargetargs)
+- [UseEventListenerWithExplicitTargetArgs](#useeventlistenerwithexplicittargetargs)
 - [RestrictedContext](#restrictedcontext)
 - [SafeContext](#safecontext)
 
-## useEventListener()
+## useEventListener
+
+```ts
+const useEventListener: UseEventListener;
+```
+
+Defined in: [hooks/useEventListener.ts:135](https://github.com/aweebit/react-essentials/blob/v0.8.1/src/hooks/useEventListener.ts#L135)
 
 Adds `handler` as a listener for the event `eventName` of `target` with the
 provided `options` applied
 
+The following call signatures are available:
+
+```ts
+function useEventListener(eventName, handler, options?): void;
+function useEventListener(target, eventName, handler, options?): void;
+```
+
+For the full definition of the hook's type, see [`UseEventListener`](#useeventlistener).
+
 If `target` is not provided, `window` is used instead.
 
 If `target` is `null`, no event listener is added. This is useful when
@@ -33,253 +64,33 @@ useEventListener(document, 'visibilitychange', () => {
 });
 
 const buttonRef = useRef<HTMLButtonElement>(null);
-useEventListener(buttonRef.current, 'click', () => console.log('click'));
-```
-
-### Call Signature
-
-```ts
-function useEventListener<K>(eventName, handler, options?): void;
-```
-
-Defined in: [hooks/useEventListener.ts:99](https://github.com/aweebit/react-essentials/blob/v0.7.0/src/hooks/useEventListener.ts#L99)
-
-#### Type Parameters
-
-<table>
-<thead>
-<tr>
-<th>Type Parameter</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td>
-
-`K` _extends_ keyof `WindowEventMap`
-
-</td>
-</tr>
-</tbody>
-</table>
-
-#### Parameters
-
-<table>
-<thead>
-<tr>
-<th>Parameter</th>
-<th>Type</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td>
-
-`eventName`
-
-</td>
-<td>
-
-`K`
-
-</td>
-</tr>
-<tr>
-<td>
-
-`handler`
-
-</td>
-<td>
-
-(`this`, `event`) => `void`
-
-</td>
-</tr>
-<tr>
-<td>
-
-`options?`
-
-</td>
-<td>
-
-`boolean` \| `AddEventListenerOptions`
-
-</td>
-</tr>
-</tbody>
-</table>
-
-#### Returns
-
-`void`
-
-#### See
-
-[`useEventListener`](#useeventlistener)
-
-### Call Signature
-
-```ts
-function useEventListener<T>(target, eventName, handler, options?): void;
+useEventListener(buttonRef, 'click', () => console.log('click'));
 ```
 
-Defined in: [hooks/useEventListener.ts:108](https://github.com/aweebit/react-essentials/blob/v0.7.0/src/hooks/useEventListener.ts#L108)
-
-#### Type Parameters
-
-<table>
-<thead>
-<tr>
-<th>Type Parameter</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td>
-
-`T` _extends_ `EventTarget`
-
-</td>
-</tr>
-</tbody>
-</table>
-
-#### Parameters
-
-<table>
-<thead>
-<tr>
-<th>Parameter</th>
-<th>Type</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td>
-
-`target`
-
-</td>
-<td>
-
-`null` \| `T`
-
-</td>
-</tr>
-<tr>
-<td>
-
-`eventName`
-
-</td>
-<td>
-
-`string`
-
-</td>
-</tr>
-<tr>
-<td>
-
-`handler`
-
-</td>
-<td>
-
-(`this`, `event`) => `void`
-
-</td>
-</tr>
-<tr>
-<td>
-
-`options?`
-
-</td>
-<td>
-
-`boolean` \| `AddEventListenerOptions`
-
-</td>
-</tr>
-</tbody>
-</table>
-
-#### Returns
-
-`void`
-
-#### See
+### See
 
-[`useEventListener`](#useeventlistener)
+[`UseEventListener`](#useeventlistener)
 
 ---
 
-## useForceUpdate()
+## ~~useForceUpdate()~~
 
 ```ts
 function useForceUpdate(callback?): [() => void, bigint];
 ```
 
-Defined in: [hooks/useForceUpdate.ts:81](https://github.com/aweebit/react-essentials/blob/v0.7.0/src/hooks/useForceUpdate.ts#L81)
+Defined in: [hooks/useForceUpdate.ts:37](https://github.com/aweebit/react-essentials/blob/v0.8.1/src/hooks/useForceUpdate.ts#L37)
 
 Enables you to imperatively trigger re-rendering of components
 
 This hook is designed in the most general way possible in order to cover all
 imaginable use cases.
 
-### Example
+### Deprecated
 
-Sometimes, React's immutability constraints mean too much unnecessary copying
-of data when new data arrives at a high frequency. In such cases, it might be
-desirable to ignore the constraints by embracing imperative patterns.
-Here is an example of a scenario where that can make sense:
-
-```tsx
-type SensorData = { timestamp: number; value: number };
-const sensorDataRef = useRef<SensorData[]>([]);
-const mostRecentSensorDataTimestampRef = useRef<number>(0);
-
-const [forceUpdate, updateCount] = useForceUpdate();
-// Limiting the frequency of forced re-renders with some throttle function:
-const throttledForceUpdateRef = useRef(throttle(forceUpdate));
-
-useEffect(() => {
-  return sensorDataObservable.subscribe((data: SensorData) => {
-    // Imagine new sensor data arrives every 1 millisecond. If we were following
-    // React's immutability rules by creating a new array every time, the data
-    // that's already there would have to be copied many times before the new
-    // data would even get a chance to be reflected in the UI for the first time
-    // because it typically takes much longer than 1 millisecond for a new frame
-    // to be displayed. To prevent the waste of computational resources, we just
-    // mutate the existing array every time instead:
-    sensorDataRef.current.push(data);
-    if (data.timestamp > mostRecentSensorDataTimestampRef.current) {
-      mostRecentSensorDataTimestampRef.current = data.timestamp;
-    }
-    throttledForceUpdateRef.current();
-  });
-}, []);
-
-const [timeWindow, setTimeWindow] = useState(1000);
-const selectedSensorData = useMemo(
-  () => {
-    // Keep this line if you don't want to disable the
-    // react-hooks/exhaustive-deps ESLint rule:
-    updateCount;
-    const threshold = mostRecentSensorDataTimestampRef.current - timeWindow;
-    return sensorDataRef.current.filter(
-      ({ timestamp }) => timestamp >= threshold,
-    );
-  },
-  // sensorDataRef.current always references the same array, so listing it as a
-  // dependency is pointless. Instead, updateCount should be used:
-  [updateCount, timeWindow],
-);
-```
+This hook encourages patterns that are unsafe in Concurrent React.
+For details and ideas on how to get rid of it, please check the discussion at
+https://www.reddit.com/r/react/comments/1nqcsri/comment/ng76cv5/.
 
 ### Parameters
 
@@ -344,11 +155,18 @@ function useReducerWithDeps<S, A>(
 ): [S, ActionDispatch<A>];
 ```
 
-Defined in: [hooks/useReducerWithDeps.ts:52](https://github.com/aweebit/react-essentials/blob/v0.7.0/src/hooks/useReducerWithDeps.ts#L52)
+Defined in: [hooks/useReducerWithDeps.ts:59](https://github.com/aweebit/react-essentials/blob/v0.8.1/src/hooks/useReducerWithDeps.ts#L59)
 
 `useReducer` hook with an additional dependency array `deps` that resets the
 state to `initialState` when dependencies change
 
+This hook is the reducer pattern counterpart of [`useStateWithDeps`](#usestatewithdeps).
+
+Due to React's limitations, a change in dependencies always causes two
+renders when using this hook. The result of the first render is thrown away
+as described in
+[useState > Storing information from previous renders](https://react.dev/reference/react/useState#storing-information-from-previous-renders).
+
 For motivation and examples, see
 https://github.com/facebook/react/issues/33041.
 
@@ -480,11 +298,16 @@ function useStateWithDeps<S>(
 ): [S, Dispatch<SetStateAction<S>>];
 ```
 
-Defined in: [hooks/useStateWithDeps.ts:66](https://github.com/aweebit/react-essentials/blob/v0.7.0/src/hooks/useStateWithDeps.ts#L66)
+Defined in: [hooks/useStateWithDeps.ts:62](https://github.com/aweebit/react-essentials/blob/v0.8.1/src/hooks/useStateWithDeps.ts#L62)
 
 `useState` hook with an additional dependency array `deps` that resets the
 state to `initialState` when dependencies change
 
+Due to React's limitations, a change in dependencies always causes two
+renders when using this hook. The result of the first render is thrown away
+as described in
+[useState > Storing information from previous renders](https://react.dev/reference/react/useState#storing-information-from-previous-renders).
+
 For motivation and more examples, see
 https://github.com/facebook/react/issues/33041.
 
@@ -504,7 +327,7 @@ const activityOptionsByTimeOfDay: {
   evening: ['board games', 'dinner'],
 };
 
-export function Example() {
+function Example() {
   const [timeOfDay, setTimeOfDay] = useState<TimeOfDay>('morning');
 
   const activityOptions = activityOptionsByTimeOfDay[timeOfDay];
@@ -607,7 +430,7 @@ function createSafeContext<T>(): <DisplayName>(
 ) => SafeContext<DisplayName, T>;
 ```
 
-Defined in: [misc/createSafeContext.ts:89](https://github.com/aweebit/react-essentials/blob/v0.7.0/src/misc/createSafeContext.ts#L89)
+Defined in: [misc/createSafeContext.ts:95](https://github.com/aweebit/react-essentials/blob/v0.8.1/src/misc/createSafeContext.ts#L95)
 
 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,
@@ -744,6 +567,337 @@ A function that accepts a single string argument `displayName` (e.g.
 
 [`SafeContext`](#safecontext)\<`DisplayName`, `T`\>
 
+### See
+
+[`SafeContext`](#safecontext)
+
+---
+
+## UseEventListener
+
+```ts
+type UseEventListener = UseEventListenerWithImplicitWindowTarget &
+  UseEventListenerWithExplicitGlobalTarget &
+  UseEventListenerWithAnyExplicitTarget;
+```
+
+Defined in: [hooks/useEventListener.ts:12](https://github.com/aweebit/react-essentials/blob/v0.8.1/src/hooks/useEventListener.ts#L12)
+
+The type of [`useEventListener`](#useeventlistener-1)
+
+### See
+
+[`useEventListener`](#useeventlistener-1),
+[`UseEventListenerWithImplicitWindowTarget`](#useeventlistenerwithimplicitwindowtarget),
+[`UseEventListenerWithExplicitGlobalTarget`](#useeventlistenerwithexplicitglobaltarget),
+[`UseEventListenerWithAnyExplicitTarget`](#useeventlistenerwithanyexplicittarget)
+
+---
+
+## UseEventListenerWithImplicitWindowTarget()
+
+```ts
+type UseEventListenerWithImplicitWindowTarget = <K>(...args) => void;
+```
+
+Defined in: [hooks/useEventListener.ts:21](https://github.com/aweebit/react-essentials/blob/v0.8.1/src/hooks/useEventListener.ts#L21)
+
+### Type Parameters
+
+<table>
+<thead>
+<tr>
+<th>Type Parameter</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+
+`K` _extends_ keyof `WindowEventMap`
+
+</td>
+</tr>
+</tbody>
+</table>
+
+### Parameters
+
+<table>
+<thead>
+<tr>
+<th>Parameter</th>
+<th>Type</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+
+...`args`
+
+</td>
+<td>
+
+[`UseEventListenerWithImplicitWindowTargetArgs`](#useeventlistenerwithimplicitwindowtargetargs)\<`K`\>
+
+</td>
+</tr>
+</tbody>
+</table>
+
+### Returns
+
+`void`
+
+### See
+
+[`useEventListener`](#useeventlistener-1),
+[`UseEventListenerWithImplicitWindowTargetArgs`](#useeventlistenerwithimplicitwindowtargetargs)
+
+---
+
+## UseEventListenerWithExplicitGlobalTarget
+
+```ts
+type UseEventListenerWithExplicitGlobalTarget =
+  UseEventListenerWithExplicitTarget<Window, WindowEventMap> &
+    UseEventListenerWithExplicitTarget<Document, DocumentEventMap> &
+    UseEventListenerWithExplicitTarget<HTMLElement, HTMLElementEventMap> &
+    UseEventListenerWithExplicitTarget<SVGElement, SVGElementEventMap> &
+    UseEventListenerWithExplicitTarget<MathMLElement, MathMLElementEventMap>;
+```
+
+Defined in: [hooks/useEventListener.ts:32](https://github.com/aweebit/react-essentials/blob/v0.8.1/src/hooks/useEventListener.ts#L32)
+
+### See
+
+[`useEventListener`](#useeventlistener-1),
+[`UseEventListenerWithExplicitTarget`](#useeventlistenerwithexplicittarget)
+
+---
+
+## UseEventListenerWithExplicitTarget()
+
+```ts
+type UseEventListenerWithExplicitTarget<Target, EventMap> = <T, K>(
+  ...args
+) => void;
+```
+
+Defined in: [hooks/useEventListener.ts:44](https://github.com/aweebit/react-essentials/blob/v0.8.1/src/hooks/useEventListener.ts#L44)
+
+### Type Parameters
+
+<table>
+<thead>
+<tr>
+<th>Type Parameter</th>
+<th>Default type</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+
+`Target` _extends_ `EventTarget`
+
+</td>
+<td>
+
+&hyphen;
+
+</td>
+</tr>
+<tr>
+<td>
+
+`EventMap`
+
+</td>
+<td>
+
+`Record`\<`string`, `Event`\>
+
+</td>
+</tr>
+</tbody>
+</table>
+
+### Type Parameters
+
+<table>
+<thead>
+<tr>
+<th>Type Parameter</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+
+`T` _extends_ `Target`
+
+</td>
+</tr>
+<tr>
+<td>
+
+`K` _extends_ keyof `EventMap`
+
+</td>
+</tr>
+</tbody>
+</table>
+
+### Parameters
+
+<table>
+<thead>
+<tr>
+<th>Parameter</th>
+<th>Type</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+
+...`args`
+
+</td>
+<td>
+
+[`UseEventListenerWithExplicitTargetArgs`](#useeventlistenerwithexplicittargetargs)\<`EventMap`, `T`, `K`\>
+
+</td>
+</tr>
+</tbody>
+</table>
+
+### Returns
+
+`void`
+
+### See
+
+[`useEventListener`](#useeventlistener-1),
+[`UseEventListenerWithExplicitTargetArgs`](#useeventlistenerwithexplicittargetargs)
+
+---
+
+## UseEventListenerWithAnyExplicitTarget
+
+```ts
+type UseEventListenerWithAnyExplicitTarget =
+  UseEventListenerWithExplicitTarget<EventTarget>;
+```
+
+Defined in: [hooks/useEventListener.ts:56](https://github.com/aweebit/react-essentials/blob/v0.8.1/src/hooks/useEventListener.ts#L56)
+
+### See
+
+[`useEventListener`](#useeventlistener-1),
+[`UseEventListenerWithExplicitTarget`](#useeventlistenerwithexplicittarget)
+
+---
+
+## UseEventListenerWithImplicitWindowTargetArgs
+
+```ts
+type UseEventListenerWithImplicitWindowTargetArgs<K> =
+  UseEventListenerWithExplicitTargetArgs<WindowEventMap, Window, K> extends [
+    unknown,
+    ...infer Args,
+  ]
+    ? Args
+    : never;
+```
+
+Defined in: [hooks/useEventListener.ts:64](https://github.com/aweebit/react-essentials/blob/v0.8.1/src/hooks/useEventListener.ts#L64)
+
+### Type Parameters
+
+<table>
+<thead>
+<tr>
+<th>Type Parameter</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+
+`K` _extends_ keyof `WindowEventMap`
+
+</td>
+</tr>
+</tbody>
+</table>
+
+### See
+
+[`useEventListener`](#useeventlistener-1),
+[`UseEventListenerWithExplicitTargetArgs`](#useeventlistenerwithexplicittargetargs)
+
+---
+
+## UseEventListenerWithExplicitTargetArgs
+
+```ts
+type UseEventListenerWithExplicitTargetArgs<EventMap, T, K> = [
+  (
+    | T
+    | (RefObject<T> & {
+        addEventListener?: never;
+      })
+    | null
+  ),
+  K,
+  (this, event) => void,
+  AddEventListenerOptions | boolean | undefined,
+];
+```
+
+Defined in: [hooks/useEventListener.ts:78](https://github.com/aweebit/react-essentials/blob/v0.8.1/src/hooks/useEventListener.ts#L78)
+
+### Type Parameters
+
+<table>
+<thead>
+<tr>
+<th>Type Parameter</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+
+`EventMap`
+
+</td>
+</tr>
+<tr>
+<td>
+
+`T` _extends_ `EventTarget`
+
+</td>
+</tr>
+<tr>
+<td>
+
+`K` _extends_ keyof `EventMap`
+
+</td>
+</tr>
+</tbody>
+</table>
+
+### See
+
+[`useEventListener`](#useeventlistener-1)
+
 ---
 
 ## RestrictedContext
@@ -761,7 +915,7 @@ type RestrictedContext<T> =
       };
 ```
 
-Defined in: [misc/createSafeContext.ts:17](https://github.com/aweebit/react-essentials/blob/v0.7.0/src/misc/createSafeContext.ts#L17)
+Defined in: [misc/createSafeContext.ts:18](https://github.com/aweebit/react-essentials/blob/v0.8.1/src/misc/createSafeContext.ts#L18)
 
 A React context with a required `displayName` and the obsolete `Consumer`
 property purposefully omitted so that it is impossible to pass the context
@@ -801,7 +955,7 @@ type SafeContext<DisplayName, T> = {
 } & { [K in `use${DisplayName}`]: () => T };
 ```
 
-Defined in: [misc/createSafeContext.ts:27](https://github.com/aweebit/react-essentials/blob/v0.7.0/src/misc/createSafeContext.ts#L27)
+Defined in: [misc/createSafeContext.ts:30](https://github.com/aweebit/react-essentials/blob/v0.8.1/src/misc/createSafeContext.ts#L30)
 
 The return type of [`createSafeContext`](#createsafecontext)
 
@@ -833,4 +987,5 @@ The return type of [`createSafeContext`](#createsafecontext)
 
 ### See
 
-[`createSafeContext`](#createsafecontext)
+[`createSafeContext`](#createsafecontext),
+[`RestrictedContext`](#restrictedcontext)