@aweebit/react-essentials 0.9.0 → 0.10.1

package/README.md

@@ -2,22 +2,17 @@
 
 [![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)
 - [useReducerWithDeps()](#usereducerwithdeps)
 - [useStateWithDeps()](#usestatewithdeps)
+- [contextualize()](#contextualize)
 - [createSafeContext()](#createsafecontext)
+- [wrapJSX()](#wrapjsx)
 
-### Types
+### Requirements
 
-- [UseEventListener](#useeventlistener-1)
-- [SafeContext](#safecontext)
+- React ≥ 18
+- TypeScript ≥ 5.4
 
 ## useEventListener
 
@@ -25,7 +20,7 @@
 const useEventListener: UseEventListener;
 ```
 
-Defined in: [hooks/useEventListener.ts:135](https://github.com/aweebit/react-essentials/blob/v0.9.0/src/hooks/useEventListener.ts#L135)
+Defined in: [hooks/useEventListener.ts:135](https://github.com/aweebit/react-essentials/blob/v0.10.1/src/hooks/useEventListener.ts#L135)
 
 Adds `handler` as a listener for the event `eventName` of `target` with the
 provided `options` applied
@@ -37,7 +32,7 @@ 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).
+For the full definition of the hook's type, see [`UseEventListener`](#useeventlistener-1).
 
 If `target` is not provided, `window` is used instead.
 
@@ -62,7 +57,7 @@ useEventListener(buttonRef, 'click', () => console.log('click'));
 
 ### See
 
-[`UseEventListener`](#useeventlistener)
+[`UseEventListener`](#useeventlistener-1)
 
 ---
 
@@ -76,7 +71,7 @@ function useReducerWithDeps<S, A>(
 ): [S, ActionDispatch<A>];
 ```
 
-Defined in: [hooks/useReducerWithDeps.ts:59](https://github.com/aweebit/react-essentials/blob/v0.9.0/src/hooks/useReducerWithDeps.ts#L59)
+Defined in: [hooks/useReducerWithDeps.ts:59](https://github.com/aweebit/react-essentials/blob/v0.10.1/src/hooks/useReducerWithDeps.ts#L59)
 
 `useReducer` hook with an additional dependency array `deps` that resets the
 state to `initialState` when dependencies change
@@ -219,7 +214,7 @@ function useStateWithDeps<S>(
 ): [S, Dispatch<SetStateAction<S>>];
 ```
 
-Defined in: [hooks/useStateWithDeps.ts:62](https://github.com/aweebit/react-essentials/blob/v0.9.0/src/hooks/useStateWithDeps.ts#L62)
+Defined in: [hooks/useStateWithDeps.ts:62](https://github.com/aweebit/react-essentials/blob/v0.10.1/src/hooks/useStateWithDeps.ts#L62)
 
 `useState` hook with an additional dependency array `deps` that resets the
 state to `initialState` when dependencies change
@@ -343,15 +338,113 @@ Dependencies that reset the state to `initialState`
 
 ---
 
+## contextualize()
+
+```ts
+function contextualize(jsx): ContextualizePipe;
+```
+
+Defined in: [misc/contextualize.tsx:79](https://github.com/aweebit/react-essentials/blob/v0.10.1/src/misc/contextualize.tsx#L79)
+
+An alternative way to provide context values to component trees that avoids
+ever-increasing indentation
+
+A context-specific version of the more general [`wrapJSX`](#wrapjsx) function.
+
+### Example
+
+```tsx
+// Before:
+return (
+  <CourseIdContext.Provider value={courseId}>
+    <DeckIdContext.Provider value={deckId}>
+      <FlashcardsContext.Provider value={flashcards}>
+        <EventHandlersContext.Provider value={eventHandlers}>
+          <Header />
+          <Main />
+          <Footer />
+        </EventHandlersContext.Provider>
+      </FlashcardsContext.Provider>
+    </DeckIdContext.Provider>
+  </CourseIdContext.Provider>
+);
+
+// After:
+const jsx = (
+  <>
+    <Header />
+    <Main />
+    <Footer />
+  </>
+);
+
+return contextualize(jsx)
+  .with(EventHandlersContext, eventHandlers)
+  .with(FlashcardsContext, flashcards)
+  .with(DeckIdContext, deckId)
+  .with(CourseIdContext, courseId)
+  .end();
+```
+
+### Parameters
+
+<table>
+<thead>
+<tr>
+<th>Parameter</th>
+<th>Type</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+
+`jsx`
+
+</td>
+<td>
+
+`Element`
+
+</td>
+<td>
+
+The JSX to contextualize
+
+</td>
+</tr>
+</tbody>
+</table>
+
+### Returns
+
+[`ContextualizePipe`](#contextualizepipe)
+
+An object with the following properties:
+
+- `with`: a function that accepts a context `Context` and a value `value` for
+  it as arguments and returns
+  `contextualize(<Context.Provider value={value}>{jsx}</Context.Provider>)`
+- `end`: a function that returns `jsx`
+
+### See
+
+[`ContextualizePipe`](#contextualizepipe)
+
+---
+
 ## createSafeContext()
 
 ```ts
-function createSafeContext<T>(): <DisplayName>(
-  displayName,
-) => SafeContext<DisplayName, T>;
+function createSafeContext<T>(): <DisplayName>(displayName) => {
+  [K in `${string}Context`]: Context<T>;
+} & {
+  [K in `use${string}`]: () => T;
+};
 ```
 
-Defined in: [misc/createSafeContext.ts:95](https://github.com/aweebit/react-essentials/blob/v0.9.0/src/misc/createSafeContext.ts#L95)
+Defined in: [misc/createSafeContext.ts:62](https://github.com/aweebit/react-essentials/blob/v0.10.1/src/misc/createSafeContext.ts#L62)
 
 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,
@@ -371,7 +464,7 @@ enum Direction {
   Right,
 }
 
-// Before
+// Before:
 const DirectionContext = createContext<Direction | undefined>(undefined);
 DirectionContext.displayName = 'DirectionContext';
 
@@ -388,7 +481,7 @@ const useDirection = () => {
   return direction;
 };
 
-// After
+// After:
 const { DirectionContext, useDirection } =
   createSafeContext<Direction>()('Direction'); // That's it :)
 
@@ -437,7 +530,7 @@ A function that accepts a single string argument `displayName` (e.g.
   current context value if one was provided, or throws an error otherwise
 
 ```ts
-<DisplayName>(displayName): SafeContext<DisplayName, T>;
+<DisplayName>(displayName): { [K in `${string}Context`]: Context<T> } & { [K in `use${string}`]: () => T };
 ```
 
 #### Type Parameters
@@ -486,11 +579,101 @@ A function that accepts a single string argument `displayName` (e.g.
 
 #### Returns
 
-[`SafeContext`](#safecontext)\<`DisplayName`, `T`\>
+``{ [K in `${string}Context`]: Context<T> }`` & ``{ [K in `use${string}`]: () => T }``
+
+---
+
+## wrapJSX()
+
+```ts
+function wrapJSX(jsx): JSXWrapPipe;
+```
+
+Defined in: [misc/wrapJSX.tsx:93](https://github.com/aweebit/react-essentials/blob/v0.10.1/src/misc/wrapJSX.tsx#L93)
+
+An alternative way to compose JSX that avoids ever-increasing indentation
+
+A more general version of the context-specific [`contextualize`](#contextualize)
+function.
+
+### Example
+
+```tsx
+// Before:
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <I18nextProvider i18n={i18n}>
+      <QueryClientProvider client={queryClient}>
+        <NuqsAdapter>
+          <ThemeProvider theme={theme}>
+            <ToasterProvider>
+              <App />
+            </ToasterProvider>
+          </ThemeProvider>
+        </NuqsAdapter>
+      </QueryClientProvider>
+    </I18nextProvider>
+  </StrictMode>,
+);
+
+// After:
+createRoot(document.getElementById('root')!).render(
+  wrapJSX(<App />)
+    .with(ToasterProvider)
+    .with(ThemeProvider, { theme })
+    .with(NuqsAdapter)
+    .with(QueryClientProvider, { client: queryClient })
+    .with(I18nextProvider, { i18n })
+    .with(StrictMode)
+    .end(),
+);
+```
+
+### Parameters
+
+<table>
+<thead>
+<tr>
+<th>Parameter</th>
+<th>Type</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+
+`jsx`
+
+</td>
+<td>
+
+`Element`
+
+</td>
+<td>
+
+The JSX to wrap
+
+</td>
+</tr>
+</tbody>
+</table>
+
+### Returns
+
+[`JSXWrapPipe`](#jsxwrappipe)
+
+An object with the following properties:
+
+- `with`: a function that accepts a component `Component` and props `props`
+  for it as arguments and returns
+  `wrapJSX(<Component {...props}>{jsx}</Component>)`
+- `end`: a function that returns `jsx`
 
 ### See
 
-[`SafeContext`](#safecontext)
+[`JSXWrapPipe`](#jsxwrappipe)
 
 ---
 
@@ -502,13 +685,13 @@ type UseEventListener = UseEventListenerWithImplicitWindowTarget &
   UseEventListenerWithAnyExplicitTarget;
 ```
 
-Defined in: [hooks/useEventListener.ts:12](https://github.com/aweebit/react-essentials/blob/v0.9.0/src/hooks/useEventListener.ts#L12)
+Defined in: [hooks/useEventListener.ts:12](https://github.com/aweebit/react-essentials/blob/v0.10.1/src/hooks/useEventListener.ts#L12)
 
-The type of [`useEventListener`](#useeventlistener-1)
+The type of [`useEventListener`](#useeventlistener)
 
 ### See
 
-[`useEventListener`](#useeventlistener-1),
+[`useEventListener`](#useeventlistener),
 [`UseEventListenerWithImplicitWindowTarget`](#useeventlistenerwithimplicitwindowtarget),
 [`UseEventListenerWithExplicitGlobalTarget`](#useeventlistenerwithexplicitglobaltarget),
 [`UseEventListenerWithAnyExplicitTarget`](#useeventlistenerwithanyexplicittarget)
@@ -521,7 +704,7 @@ The type of [`useEventListener`](#useeventlistener-1)
 type UseEventListenerWithImplicitWindowTarget = <K>(...args) => void;
 ```
 
-Defined in: [hooks/useEventListener.ts:21](https://github.com/aweebit/react-essentials/blob/v0.9.0/src/hooks/useEventListener.ts#L21)
+Defined in: [hooks/useEventListener.ts:21](https://github.com/aweebit/react-essentials/blob/v0.10.1/src/hooks/useEventListener.ts#L21)
 
 ### Type Parameters
 
@@ -573,7 +756,7 @@ Defined in: [hooks/useEventListener.ts:21](https://github.com/aweebit/react-esse
 
 ### See
 
-[`useEventListener`](#useeventlistener-1),
+[`useEventListener`](#useeventlistener),
 [`UseEventListenerWithImplicitWindowTargetArgs`](#useeventlistenerwithimplicitwindowtargetargs)
 
 ---
@@ -589,11 +772,11 @@ type UseEventListenerWithExplicitGlobalTarget =
     UseEventListenerWithExplicitTarget<MathMLElement, MathMLElementEventMap>;
 ```
 
-Defined in: [hooks/useEventListener.ts:32](https://github.com/aweebit/react-essentials/blob/v0.9.0/src/hooks/useEventListener.ts#L32)
+Defined in: [hooks/useEventListener.ts:32](https://github.com/aweebit/react-essentials/blob/v0.10.1/src/hooks/useEventListener.ts#L32)
 
 ### See
 
-[`useEventListener`](#useeventlistener-1),
+[`useEventListener`](#useeventlistener),
 [`UseEventListenerWithExplicitTarget`](#useeventlistenerwithexplicittarget)
 
 ---
@@ -606,7 +789,7 @@ type UseEventListenerWithExplicitTarget<Target, EventMap> = <T, K>(
 ) => void;
 ```
 
-Defined in: [hooks/useEventListener.ts:44](https://github.com/aweebit/react-essentials/blob/v0.9.0/src/hooks/useEventListener.ts#L44)
+Defined in: [hooks/useEventListener.ts:44](https://github.com/aweebit/react-essentials/blob/v0.10.1/src/hooks/useEventListener.ts#L44)
 
 ### Type Parameters
 
@@ -691,7 +874,7 @@ Defined in: [hooks/useEventListener.ts:44](https://github.com/aweebit/react-esse
 
 ### See
 
-[`useEventListener`](#useeventlistener-1),
+[`useEventListener`](#useeventlistener),
 [`UseEventListenerWithExplicitTargetArgs`](#useeventlistenerwithexplicittargetargs)
 
 ---
@@ -705,11 +888,11 @@ type UseEventListenerWithAnyExplicitTarget = UseEventListenerWithExplicitTarget<
 >;
 ```
 
-Defined in: [hooks/useEventListener.ts:56](https://github.com/aweebit/react-essentials/blob/v0.9.0/src/hooks/useEventListener.ts#L56)
+Defined in: [hooks/useEventListener.ts:56](https://github.com/aweebit/react-essentials/blob/v0.10.1/src/hooks/useEventListener.ts#L56)
 
 ### See
 
-[`useEventListener`](#useeventlistener-1),
+[`useEventListener`](#useeventlistener),
 [`UseEventListenerWithExplicitTarget`](#useeventlistenerwithexplicittarget)
 
 ---
@@ -726,7 +909,7 @@ type UseEventListenerWithImplicitWindowTargetArgs<K> =
     : never;
 ```
 
-Defined in: [hooks/useEventListener.ts:64](https://github.com/aweebit/react-essentials/blob/v0.9.0/src/hooks/useEventListener.ts#L64)
+Defined in: [hooks/useEventListener.ts:64](https://github.com/aweebit/react-essentials/blob/v0.10.1/src/hooks/useEventListener.ts#L64)
 
 ### Type Parameters
 
@@ -749,7 +932,7 @@ Defined in: [hooks/useEventListener.ts:64](https://github.com/aweebit/react-esse
 
 ### See
 
-[`useEventListener`](#useeventlistener-1),
+[`useEventListener`](#useeventlistener),
 [`UseEventListenerWithExplicitTargetArgs`](#useeventlistenerwithexplicittargetargs)
 
 ---
@@ -771,7 +954,7 @@ type UseEventListenerWithExplicitTargetArgs<EventMap, T, K> = [
 ];
 ```
 
-Defined in: [hooks/useEventListener.ts:78](https://github.com/aweebit/react-essentials/blob/v0.9.0/src/hooks/useEventListener.ts#L78)
+Defined in: [hooks/useEventListener.ts:78](https://github.com/aweebit/react-essentials/blob/v0.10.1/src/hooks/useEventListener.ts#L78)
 
 ### Type Parameters
 
@@ -808,21 +991,74 @@ Defined in: [hooks/useEventListener.ts:78](https://github.com/aweebit/react-esse
 
 ### See
 
-[`useEventListener`](#useeventlistener-1)
+[`useEventListener`](#useeventlistener)
 
 ---
 
-## SafeContext
+## ContextualizePipe
 
 ```ts
-type SafeContext<DisplayName, T> = {
-  [K in `${DisplayName}Context`]: RestrictedContext<T>;
-} & { [K in `use${DisplayName}`]: () => T };
+type ContextualizePipe = {
+  with: ContextualizeWith;
+  end: () => React.JSX.Element;
+};
 ```
 
-Defined in: [misc/createSafeContext.ts:13](https://github.com/aweebit/react-essentials/blob/v0.9.0/src/misc/createSafeContext.ts#L13)
+Defined in: [misc/contextualize.tsx:13](https://github.com/aweebit/react-essentials/blob/v0.10.1/src/misc/contextualize.tsx#L13)
+
+The return type of [`contextualize`](#contextualize)
+
+### See
+
+[`contextualize`](#contextualize),
+[`ContextualizeWith`](#contextualizewith)
+
+### Properties
+
+<table>
+<thead>
+<tr>
+<th>Property</th>
+<th>Type</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
 
-The return type of [`createSafeContext`](#createsafecontext)
+<a id="with"></a> `with`
+
+</td>
+<td>
+
+[`ContextualizeWith`](#contextualizewith)
+
+</td>
+</tr>
+<tr>
+<td>
+
+<a id="end"></a> `end`
+
+</td>
+<td>
+
+() => `React.JSX.Element`
+
+</td>
+</tr>
+</tbody>
+</table>
+
+---
+
+## ContextualizeWith()
+
+```ts
+type ContextualizeWith = <T>(Context, value) => ContextualizePipe;
+```
+
+Defined in: [misc/contextualize.tsx:23](https://github.com/aweebit/react-essentials/blob/v0.10.1/src/misc/contextualize.tsx#L23)
 
 ### Type Parameters
 
@@ -836,48 +1072,125 @@ The return type of [`createSafeContext`](#createsafecontext)
 <tr>
 <td>
 
-`DisplayName` _extends_ `string`
+`T`
 
 </td>
 </tr>
+</tbody>
+</table>
+
+### Parameters
+
+<table>
+<thead>
+<tr>
+<th>Parameter</th>
+<th>Type</th>
+</tr>
+</thead>
+<tbody>
 <tr>
 <td>
 
-`T`
+`Context`
+
+</td>
+<td>
+
+`Context`\<`T`\>
+
+</td>
+</tr>
+<tr>
+<td>
+
+`value`
+
+</td>
+<td>
+
+`NoInfer`\<`T`\>
 
 </td>
 </tr>
 </tbody>
 </table>
 
+### Returns
+
+[`ContextualizePipe`](#contextualizepipe)
+
 ### See
 
-[`createSafeContext`](#createsafecontext),
-[`RestrictedContext`](#restrictedcontext)
+[`contextualize`](#contextualize),
+[`ContextualizePipe`](#contextualizepipe)
 
 ---
 
-## RestrictedContext
+## JSXWrapPipe
 
 ```ts
-type RestrictedContext<T> =
-  Context<T> extends Provider<T>
-    ? {
-        Provider: Provider<T>;
-        displayName: string;
-      } & Provider<T>
-    : {
-        Provider: Provider<T>;
-        displayName: string;
-      };
+type JSXWrapPipe = {
+  with: WrapJSXWith;
+  end: () => React.JSX.Element;
+};
 ```
 
-Defined in: [misc/createSafeContext.ts:31](https://github.com/aweebit/react-essentials/blob/v0.9.0/src/misc/createSafeContext.ts#L31)
+Defined in: [misc/wrapJSX.tsx:17](https://github.com/aweebit/react-essentials/blob/v0.10.1/src/misc/wrapJSX.tsx#L17)
+
+The return type of [`wrapJSX`](#wrapjsx)
 
-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)
+### See
+
+[`wrapJSX`](#wrapjsx),
+[`WrapJSXWith`](#wrapjsxwith)
+
+### Properties
+
+<table>
+<thead>
+<tr>
+<th>Property</th>
+<th>Type</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+
+<a id="with-1"></a> `with`
+
+</td>
+<td>
+
+[`WrapJSXWith`](#wrapjsxwith)
+
+</td>
+</tr>
+<tr>
+<td>
+
+<a id="end-1"></a> `end`
+
+</td>
+<td>
+
+() => `React.JSX.Element`
+
+</td>
+</tr>
+</tbody>
+</table>
+
+---
+
+## WrapJSXWith()
+
+```ts
+type WrapJSXWith = <C>(...args) => JSXWrapPipe;
+```
+
+Defined in: [misc/wrapJSX.tsx:27](https://github.com/aweebit/react-essentials/blob/v0.10.1/src/misc/wrapJSX.tsx#L27)
 
 ### Type Parameters
 
@@ -891,13 +1204,43 @@ as an argument to `useContext` or `use` (the hook produced with
 <tr>
 <td>
 
-`T`
+`C` _extends_ keyof `JSX.IntrinsicElements` \| `JSXElementConstructor`\<`any`\>
+
+</td>
+</tr>
+</tbody>
+</table>
+
+### Parameters
+
+<table>
+<thead>
+<tr>
+<th>Parameter</th>
+<th>Type</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+
+...`args`
+
+</td>
+<td>
+
+\[`C`, `...(Record<never, unknown> extends Omit<ComponentProps<C>, "children"> ? [props?: React.JSX.IntrinsicAttributes & Omit<ComponentProps<C>, "children">] : [props: React.JSX.IntrinsicAttributes & Omit<ComponentProps<C>, "children">])`\]
 
 </td>
 </tr>
 </tbody>
 </table>
 
+### Returns
+
+[`JSXWrapPipe`](#jsxwrappipe)
+
 ### See
 
-[`createSafeContext`](#createsafecontext)
+[`wrapJSX`](#wrapjsx),
+[`JSXWrapPipe`](#jsxwrappipe)