@aweebit/react-essentials 0.6.0 → 0.8.0

package/README.md

@@ -1,76 +1,56 @@
 # @aweebit/react-essentials
 
-## RestrictedContext
+[![NPM Version](https://img.shields.io/npm/v/%40aweebit%2Freact-essentials)](https://www.npmjs.com/package/@aweebit/react-essentials)
 
-```ts
-type RestrictedContext<T> =
-  Context<T> extends Provider<T>
-    ? {
-        Provider: Provider<T>;
-        displayName: string;
-      } & Provider<T>
-    : {
-        Provider: Provider<T>;
-        displayName: string;
-      };
-```
-
-Defined in: [misc/createSafeContext.ts:17](https://github.com/aweebit/react-essentials/blob/v0.6.0/src/misc/createSafeContext.ts#L17)
-
-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
-[`createSafeContext`](#createsafecontext) should be used instead)
+### Requirements
 
-### Type Parameters
+- React ≥ 18
+- TypeScript ≥ 5.4
 
-| Type Parameter |
-| -------------- |
-| `T`            |
+### Functions
 
-### See
+- [useEventListener()](#useeventlistener)
+- [useForceUpdate()](#useforceupdate)
+- [useReducerWithDeps()](#usereducerwithdeps)
+- [useStateWithDeps()](#usestatewithdeps)
+- [createSafeContext()](#createsafecontext)
 
-[`createSafeContext`](#createsafecontext)
+### Types
 
----
+- [UseEventListener](#useeventlistener-1)
+- [UseEventListenerWithImplicitWindowTarget](#useeventlistenerwithimplicitwindowtarget)
+- [UseEventListenerWithExplicitTarget](#useeventlistenerwithexplicittarget)
+- [UseEventListenerWithAnyExplicitTarget](#useeventlistenerwithanyexplicittarget)
+- [UseEventListenerWithImplicitWindowTargetArgs](#useeventlistenerwithimplicitwindowtargetargs)
+- [UseEventListenerWithExplicitTargetArgs](#useeventlistenerwithexplicittargetargs)
+- [RestrictedContext](#restrictedcontext)
+- [SafeContext](#safecontext)
 
-## SafeContext
+## useEventListener
 
 ```ts
-type SafeContext<DisplayName, T> = {
-  [K in `${DisplayName}Context`]: RestrictedContext<T>;
-} & { [K in `use${DisplayName}`]: () => T };
+const useEventListener: UseEventListener;
 ```
 
-Defined in: [misc/createSafeContext.ts:25](https://github.com/aweebit/react-essentials/blob/v0.6.0/src/misc/createSafeContext.ts#L25)
-
-### Type Parameters
+Defined in: [hooks/useEventListener.ts:133](https://github.com/aweebit/react-essentials/blob/v0.8.0/src/hooks/useEventListener.ts#L133)
 
-| Type Parameter                   |
-| -------------------------------- |
-| `DisplayName` _extends_ `string` |
-| `T`                              |
-
-### See
-
-[`createSafeContext`](#createsafecontext)
-
----
+Adds `handler` as a listener for the event `eventName` of `target` with the
+provided `options` applied
 
-## useEventListener()
+The following call signatures are available:
 
 ```ts
-function useEventListener<T>(eventName, handler, element?, options?): void;
+function useEventListener(eventName, handler, options?): void;
+function useEventListener(target, eventName, handler, options?): void;
 ```
 
-Defined in: [hooks/useEventListener.ts:120](https://github.com/aweebit/react-essentials/blob/v0.6.0/src/hooks/useEventListener.ts#L120)
-
-Adds `handler` as a listener for the event `eventName` of `element` with the
-provided `options` applied
+For the full definition of the hook's type, see [`UseEventListener`](#useeventlistener).
 
-If `element` is `undefined`, `window` is used instead.
+If `target` is not provided, `window` is used instead.
 
-If `element` is `null`, no event listener is added.
+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
 
@@ -79,34 +59,17 @@ useEventListener('resize', () => {
   console.log(window.innerWidth, window.innerHeight);
 });
 
-useEventListener(
-  'visibilitychange',
-  () => console.log(document.visibilityState),
-  document,
-);
+useEventListener(document, 'visibilitychange', () => {
+  console.log(document.visibilityState);
+});
 
 const buttonRef = useRef<HTMLButtonElement>(null);
-useEventListener('click', () => console.log('click'), buttonRef.current);
+useEventListener(buttonRef, 'click', () => console.log('click'));
 ```
 
-### Type Parameters
-
-| Type Parameter              |
-| --------------------------- |
-| `T` _extends_ `EventTarget` |
-
-### Parameters
+### See
 
-| Parameter   | Type                                   |
-| ----------- | -------------------------------------- |
-| `eventName` | `string`                               |
-| `handler`   | (`this`, `event`) => `void`            |
-| `element?`  | `null` \| `T`                          |
-| `options?`  | `boolean` \| `AddEventListenerOptions` |
-
-### Returns
-
-`void`
+[`UseEventListener`](#useeventlistener)
 
 ---
 
@@ -116,18 +79,104 @@ useEventListener('click', () => console.log('click'), buttonRef.current);
 function useForceUpdate(callback?): [() => void, bigint];
 ```
 
-Defined in: [hooks/useForceUpdate.ts:32](https://github.com/aweebit/react-essentials/blob/v0.6.0/src/hooks/useForceUpdate.ts#L32)
+Defined in: [hooks/useForceUpdate.ts:81](https://github.com/aweebit/react-essentials/blob/v0.8.0/src/hooks/useForceUpdate.ts#L81)
 
 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
+
+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],
+);
+```
+
 ### Parameters
 
-| Parameter   | Type         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| ----------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `callback?` | () => `void` | An optional callback function to call during renders that were triggered with `forceUpdate()` Can be used for conditionally calling state setters when state needs to be reset. That is legal and better than using effects (see [You Might Not Need an Effect \> Adjusting some state when a prop changes](https://react.dev/learn/-might-not-need-an-effect#adjusting-some-state-when-a-prop-changes)), but can often be avoided by using [`useStateWithDeps`](#usestatewithdeps) or [`useReducerWithDeps`](#usereducerwithdeps). Important: the callback function is called once per render, not once per `forceUpdate` call! If React batches `forceUpdate` calls, then it will only be called once. |
+<table>
+<thead>
+<tr>
+<th>Parameter</th>
+<th>Type</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+
+`callback?`
+
+</td>
+<td>
+
+() => `void`
+
+</td>
+<td>
+
+An optional callback function to call during renders that
+were triggered with `forceUpdate()`
+
+Can be used for conditionally calling state setters when state needs to be
+reset. That is legal and better than using effects (see
+[You Might Not Need an Effect \> Adjusting some state when a prop changes](https://react.dev/learn/-might-not-need-an-effect#adjusting-some-state-when-a-prop-changes)),
+but can often be avoided by using [`useStateWithDeps`](#usestatewithdeps) or
+[`useReducerWithDeps`](#usereducerwithdeps).
+
+Important: the callback function is called once per render, not once per
+`forceUpdate` call! If React batches `forceUpdate` calls, then it will only
+be called once.
+
+</td>
+</tr>
+</tbody>
+</table>
 
 ### Returns
 
@@ -150,11 +199,14 @@ function useReducerWithDeps<S, A>(
 ): [S, ActionDispatch<A>];
 ```
 
-Defined in: [hooks/useReducerWithDeps.ts:49](https://github.com/aweebit/react-essentials/blob/v0.6.0/src/hooks/useReducerWithDeps.ts#L49)
+Defined in: [hooks/useReducerWithDeps.ts:52](https://github.com/aweebit/react-essentials/blob/v0.8.0/src/hooks/useReducerWithDeps.ts#L52)
 
 `useReducer` hook with an additional dependency array `deps` that resets the
 state to `initialState` when dependencies change
 
+For motivation and examples, see
+https://github.com/facebook/react/issues/33041.
+
 ### On linter support
 
 The `react-hooks/exhaustive-deps` ESLint rule doesn't support hooks where
@@ -163,7 +215,7 @@ 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, additional caution is advised!
-Be sure to check no dependencies are missing from the `deps` array.
+Be sure to check that no dependencies are missing from the `deps` array.
 
 Related issue: [https://github.com/facebook/react/issues/25443](https://github.com/facebook/react/issues/25443).
 
@@ -174,18 +226,99 @@ does actually have support for dependency arrays at other positions, see
 
 ### Type Parameters
 
-| Type Parameter               |
-| ---------------------------- |
-| `S`                          |
-| `A` _extends_ `AnyActionArg` |
+<table>
+<thead>
+<tr>
+<th>Type Parameter</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+
+`S`
+
+</td>
+</tr>
+<tr>
+<td>
+
+`A` _extends_ `AnyActionArg`
+
+</td>
+</tr>
+</tbody>
+</table>
 
 ### Parameters
 
-| Parameter      | Type                             | Description                                                                                                                                                                                                                                                                                                               |
-| -------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `reducer`      | (`prevState`, ...`args`) => `S`  | The reducer function that specifies how the state gets updated                                                                                                                                                                                                                                                            |
-| `initialState` | `S` \| (`previousState?`) => `S` | 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). |
-| `deps`         | `DependencyList`                 | Dependencies that reset the state to `initialState`                                                                                                                                                                                                                                                                       |
+<table>
+<thead>
+<tr>
+<th>Parameter</th>
+<th>Type</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+
+`reducer`
+
+</td>
+<td>
+
+(`prevState`, ...`args`) => `S`
+
+</td>
+<td>
+
+The reducer function that specifies how the state gets updated
+
+</td>
+</tr>
+<tr>
+<td>
+
+`initialState`
+
+</td>
+<td>
+
+`S` \| (`previousState?`) => `S`
+
+</td>
+<td>
+
+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).
+
+</td>
+</tr>
+<tr>
+<td>
+
+`deps`
+
+</td>
+<td>
+
+`DependencyList`
+
+</td>
+<td>
+
+Dependencies that reset the state to `initialState`
+
+</td>
+</tr>
+</tbody>
+</table>
 
 ### Returns
 
@@ -202,23 +335,118 @@ function useStateWithDeps<S>(
 ): [S, Dispatch<SetStateAction<S>>];
 ```
 
-Defined in: [hooks/useStateWithDeps.ts:31](https://github.com/aweebit/react-essentials/blob/v0.6.0/src/hooks/useStateWithDeps.ts#L31)
+Defined in: [hooks/useStateWithDeps.ts:65](https://github.com/aweebit/react-essentials/blob/v0.8.0/src/hooks/useStateWithDeps.ts#L65)
 
 `useState` hook with an additional dependency array `deps` that resets the
 state to `initialState` when dependencies change
 
+For motivation and more examples, see
+https://github.com/facebook/react/issues/33041.
+
+### 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 '...';
+}
+```
+
 ### Type Parameters
 
-| Type Parameter |
-| -------------- |
-| `S`            |
+<table>
+<thead>
+<tr>
+<th>Type Parameter</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+
+`S`
+
+</td>
+</tr>
+</tbody>
+</table>
 
 ### Parameters
 
-| Parameter      | Type                             | Description                                                                                                                                                                                                                                                                                                               |
-| -------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `initialState` | `S` \| (`previousState?`) => `S` | 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). |
-| `deps`         | `DependencyList`                 | Dependencies that reset the state to `initialState`                                                                                                                                                                                                                                                                       |
+<table>
+<thead>
+<tr>
+<th>Parameter</th>
+<th>Type</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+
+`initialState`
+
+</td>
+<td>
+
+`S` \| (`previousState?`) => `S`
+
+</td>
+<td>
+
+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).
+
+</td>
+</tr>
+<tr>
+<td>
+
+`deps`
+
+</td>
+<td>
+
+`DependencyList`
+
+</td>
+<td>
+
+Dependencies that reset the state to `initialState`
+
+</td>
+</tr>
+</tbody>
+</table>
 
 ### Returns
 
@@ -234,39 +462,89 @@ function createSafeContext<T>(): <DisplayName>(
 ) => SafeContext<DisplayName, T>;
 ```
 
-Defined in: [misc/createSafeContext.ts:56](https://github.com/aweebit/react-essentials/blob/v0.6.0/src/misc/createSafeContext.ts#L56)
+Defined in: [misc/createSafeContext.ts:95](https://github.com/aweebit/react-essentials/blob/v0.8.0/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,
 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
-const { ItemsContext, useItems } = createSafeContext<string[]>()('Items');
+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 = () => (
-  <ItemsContext value={['compass', 'newspaper', 'banana']}>
+  // Providing undefined as the value is not allowed 👍
+  <Direction.Provider value={Direction.Up}>
     <Child />
-  </ItemsContext>
+  </Direction.Provider>
 );
 
-const Child = () => useItems().join(', ');
+const Child = () => `Current direction: ${Direction[useDirection()]}`;
 ```
 
 ### Type Parameters
 
-| Type Parameter | Default type |
-| -------------- | ------------ |
-| `T`            | `never`      |
+<table>
+<thead>
+<tr>
+<th>Type Parameter</th>
+<th>Default type</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+
+`T`
+
+</td>
+<td>
+
+`never`
+
+</td>
+</tr>
+</tbody>
+</table>
 
 ### Returns
 
 A function that accepts a single string argument `displayName` (e.g.
-`"Items"`) and returns an object with the following properties:
+`"Direction"`) 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
+- `` `${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
 
 ```ts
@@ -275,16 +553,455 @@ A function that accepts a single string argument `displayName` (e.g.
 
 #### Type Parameters
 
-| Type Parameter                   |
-| -------------------------------- |
-| `DisplayName` _extends_ `string` |
+<table>
+<thead>
+<tr>
+<th>Type Parameter</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+
+`DisplayName` _extends_ `string`
+
+</td>
+</tr>
+</tbody>
+</table>
 
 #### Parameters
 
-| Parameter     | Type                                                                                             |
-| ------------- | ------------------------------------------------------------------------------------------------ |
-| `displayName` | \[`T`\] _extends_ \[`never`\] ? `never` : `ArgumentFallback`\<`DisplayName`, `never`, `string`\> |
+<table>
+<thead>
+<tr>
+<th>Parameter</th>
+<th>Type</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+
+`displayName`
+
+</td>
+<td>
+
+\[`T`\] _extends_ \[`never`\] ? `never` : `ArgumentFallback`\<`DisplayName`, `never`, `string`\>
+
+</td>
+</tr>
+</tbody>
+</table>
 
 #### Returns
 
 [`SafeContext`](#safecontext)\<`DisplayName`, `T`\>
+
+### See
+
+[`SafeContext`](#safecontext)
+
+---
+
+## UseEventListener
+
+```ts
+type UseEventListener = UseEventListenerWithImplicitWindowTarget &
+  UseEventListenerWithExplicitTarget<Window, WindowEventMap> &
+  UseEventListenerWithExplicitTarget<Document, DocumentEventMap> &
+  UseEventListenerWithExplicitTarget<HTMLElement, HTMLElementEventMap> &
+  UseEventListenerWithExplicitTarget<SVGElement, SVGElementEventMap> &
+  UseEventListenerWithExplicitTarget<MathMLElement, MathMLElementEventMap> &
+  UseEventListenerWithAnyExplicitTarget;
+```
+
+Defined in: [hooks/useEventListener.ts:19](https://github.com/aweebit/react-essentials/blob/v0.8.0/src/hooks/useEventListener.ts#L19)
+
+The type of [`useEventListener`](#useeventlistener-1)
+
+### See
+
+[`useEventListener`](#useeventlistener-1),
+[`UseEventListenerWithImplicitWindowTarget`](#useeventlistenerwithimplicitwindowtarget),
+[`UseEventListenerWithExplicitTarget`](#useeventlistenerwithexplicittarget),
+[`UseEventListenerWithAnyExplicitTarget`](#useeventlistenerwithanyexplicittarget)
+
+---
+
+## UseEventListenerWithImplicitWindowTarget()
+
+```ts
+type UseEventListenerWithImplicitWindowTarget = <K>(...args) => void;
+```
+
+Defined in: [hooks/useEventListener.ts:31](https://github.com/aweebit/react-essentials/blob/v0.8.0/src/hooks/useEventListener.ts#L31)
+
+### 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)
+
+---
+
+## UseEventListenerWithExplicitTarget()
+
+```ts
+type UseEventListenerWithExplicitTarget<Target, EventMap> = <T, K>(
+  ...args
+) => void;
+```
+
+Defined in: [hooks/useEventListener.ts:42](https://github.com/aweebit/react-essentials/blob/v0.8.0/src/hooks/useEventListener.ts#L42)
+
+### 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:54](https://github.com/aweebit/react-essentials/blob/v0.8.0/src/hooks/useEventListener.ts#L54)
+
+### 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:62](https://github.com/aweebit/react-essentials/blob/v0.8.0/src/hooks/useEventListener.ts#L62)
+
+### 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:76](https://github.com/aweebit/react-essentials/blob/v0.8.0/src/hooks/useEventListener.ts#L76)
+
+### 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
+
+```ts
+type RestrictedContext<T> =
+  Context<T> extends Provider<T>
+    ? {
+        Provider: Provider<T>;
+        displayName: string;
+      } & Provider<T>
+    : {
+        Provider: Provider<T>;
+        displayName: string;
+      };
+```
+
+Defined in: [misc/createSafeContext.ts:18](https://github.com/aweebit/react-essentials/blob/v0.8.0/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
+as an argument to `useContext` or `use` (the hook produced with
+[`createSafeContext`](#createsafecontext) should be used instead)
+
+### Type Parameters
+
+<table>
+<thead>
+<tr>
+<th>Type Parameter</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+
+`T`
+
+</td>
+</tr>
+</tbody>
+</table>
+
+### See
+
+[`createSafeContext`](#createsafecontext)
+
+---
+
+## SafeContext
+
+```ts
+type SafeContext<DisplayName, T> = {
+  [K in `${DisplayName}Context`]: RestrictedContext<T>;
+} & { [K in `use${DisplayName}`]: () => T };
+```
+
+Defined in: [misc/createSafeContext.ts:30](https://github.com/aweebit/react-essentials/blob/v0.8.0/src/misc/createSafeContext.ts#L30)
+
+The return type of [`createSafeContext`](#createsafecontext)
+
+### Type Parameters
+
+<table>
+<thead>
+<tr>
+<th>Type Parameter</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+
+`DisplayName` _extends_ `string`
+
+</td>
+</tr>
+<tr>
+<td>
+
+`T`
+
+</td>
+</tr>
+</tbody>
+</table>
+
+### See
+
+[`createSafeContext`](#createsafecontext),
+[`RestrictedContext`](#restrictedcontext)