@aweebit/react-essentials 0.10.0 → 0.10.1

package/README.md

@@ -5,7 +5,9 @@
 - [useEventListener()](#useeventlistener)
 - [useReducerWithDeps()](#usereducerwithdeps)
 - [useStateWithDeps()](#usestatewithdeps)
+- [contextualize()](#contextualize)
 - [createSafeContext()](#createsafecontext)
+- [wrapJSX()](#wrapjsx)
 
 ### Requirements
 
@@ -18,7 +20,7 @@
 const useEventListener: UseEventListener;
 ```
 
-Defined in: [hooks/useEventListener.ts:135](https://github.com/aweebit/react-essentials/blob/v0.10.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
@@ -30,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.
 
@@ -55,7 +57,7 @@ useEventListener(buttonRef, 'click', () => console.log('click'));
 
 ### See
 
-[`UseEventListener`](#useeventlistener)
+[`UseEventListener`](#useeventlistener-1)
 
 ---
 
@@ -69,7 +71,7 @@ function useReducerWithDeps<S, A>(
 ): [S, ActionDispatch<A>];
 ```
 
-Defined in: [hooks/useReducerWithDeps.ts:59](https://github.com/aweebit/react-essentials/blob/v0.10.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
@@ -212,7 +214,7 @@ function useStateWithDeps<S>(
 ): [S, Dispatch<SetStateAction<S>>];
 ```
 
-Defined in: [hooks/useStateWithDeps.ts:62](https://github.com/aweebit/react-essentials/blob/v0.10.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
@@ -336,17 +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,
-) => { [K in `${string}Context`]: Context<T> } & {
+function createSafeContext<T>(): <DisplayName>(displayName) => {
+  [K in `${string}Context`]: Context<T>;
+} & {
   [K in `use${string}`]: () => T;
 };
 ```
 
-Defined in: [misc/createSafeContext.ts:62](https://github.com/aweebit/react-essentials/blob/v0.10.0/src/misc/createSafeContext.ts#L62)
+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,
@@ -366,7 +464,7 @@ enum Direction {
   Right,
 }
 
-// Before
+// Before:
 const DirectionContext = createContext<Direction | undefined>(undefined);
 DirectionContext.displayName = 'DirectionContext';
 
@@ -383,7 +481,7 @@ const useDirection = () => {
   return direction;
 };
 
-// After
+// After:
 const { DirectionContext, useDirection } =
   createSafeContext<Direction>()('Direction'); // That's it :)
 
@@ -485,6 +583,100 @@ A function that accepts a single string argument `displayName` (e.g.
 
 ---
 
+## 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
+
+[`JSXWrapPipe`](#jsxwrappipe)
+
+---
+
 ## UseEventListener
 
 ```ts
@@ -493,13 +685,13 @@ type UseEventListener = UseEventListenerWithImplicitWindowTarget &
   UseEventListenerWithAnyExplicitTarget;
 ```
 
-Defined in: [hooks/useEventListener.ts:12](https://github.com/aweebit/react-essentials/blob/v0.10.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)
@@ -512,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.10.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
 
@@ -564,7 +756,7 @@ Defined in: [hooks/useEventListener.ts:21](https://github.com/aweebit/react-esse
 
 ### See
 
-[`useEventListener`](#useeventlistener-1),
+[`useEventListener`](#useeventlistener),
 [`UseEventListenerWithImplicitWindowTargetArgs`](#useeventlistenerwithimplicitwindowtargetargs)
 
 ---
@@ -580,11 +772,11 @@ type UseEventListenerWithExplicitGlobalTarget =
     UseEventListenerWithExplicitTarget<MathMLElement, MathMLElementEventMap>;
 ```
 
-Defined in: [hooks/useEventListener.ts:32](https://github.com/aweebit/react-essentials/blob/v0.10.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)
 
 ---
@@ -597,7 +789,7 @@ type UseEventListenerWithExplicitTarget<Target, EventMap> = <T, K>(
 ) => void;
 ```
 
-Defined in: [hooks/useEventListener.ts:44](https://github.com/aweebit/react-essentials/blob/v0.10.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
 
@@ -682,7 +874,7 @@ Defined in: [hooks/useEventListener.ts:44](https://github.com/aweebit/react-esse
 
 ### See
 
-[`useEventListener`](#useeventlistener-1),
+[`useEventListener`](#useeventlistener),
 [`UseEventListenerWithExplicitTargetArgs`](#useeventlistenerwithexplicittargetargs)
 
 ---
@@ -696,11 +888,11 @@ type UseEventListenerWithAnyExplicitTarget = UseEventListenerWithExplicitTarget<
 >;
 ```
 
-Defined in: [hooks/useEventListener.ts:56](https://github.com/aweebit/react-essentials/blob/v0.10.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)
 
 ---
@@ -717,7 +909,7 @@ type UseEventListenerWithImplicitWindowTargetArgs<K> =
     : never;
 ```
 
-Defined in: [hooks/useEventListener.ts:64](https://github.com/aweebit/react-essentials/blob/v0.10.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
 
@@ -740,7 +932,7 @@ Defined in: [hooks/useEventListener.ts:64](https://github.com/aweebit/react-esse
 
 ### See
 
-[`useEventListener`](#useeventlistener-1),
+[`useEventListener`](#useeventlistener),
 [`UseEventListenerWithExplicitTargetArgs`](#useeventlistenerwithexplicittargetargs)
 
 ---
@@ -762,7 +954,7 @@ type UseEventListenerWithExplicitTargetArgs<EventMap, T, K> = [
 ];
 ```
 
-Defined in: [hooks/useEventListener.ts:78](https://github.com/aweebit/react-essentials/blob/v0.10.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
 
@@ -799,4 +991,256 @@ Defined in: [hooks/useEventListener.ts:78](https://github.com/aweebit/react-esse
 
 ### See
 
-[`useEventListener`](#useeventlistener-1)
+[`useEventListener`](#useeventlistener)
+
+---
+
+## ContextualizePipe
+
+```ts
+type ContextualizePipe = {
+  with: ContextualizeWith;
+  end: () => React.JSX.Element;
+};
+```
+
+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>
+
+<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
+
+<table>
+<thead>
+<tr>
+<th>Type Parameter</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+
+`T`
+
+</td>
+</tr>
+</tbody>
+</table>
+
+### Parameters
+
+<table>
+<thead>
+<tr>
+<th>Parameter</th>
+<th>Type</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+
+`Context`
+
+</td>
+<td>
+
+`Context`\<`T`\>
+
+</td>
+</tr>
+<tr>
+<td>
+
+`value`
+
+</td>
+<td>
+
+`NoInfer`\<`T`\>
+
+</td>
+</tr>
+</tbody>
+</table>
+
+### Returns
+
+[`ContextualizePipe`](#contextualizepipe)
+
+### See
+
+[`contextualize`](#contextualize),
+[`ContextualizePipe`](#contextualizepipe)
+
+---
+
+## JSXWrapPipe
+
+```ts
+type JSXWrapPipe = {
+  with: WrapJSXWith;
+  end: () => React.JSX.Element;
+};
+```
+
+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)
+
+### 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
+
+<table>
+<thead>
+<tr>
+<th>Type Parameter</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+
+`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
+
+[`wrapJSX`](#wrapjsx),
+[`JSXWrapPipe`](#jsxwrappipe)

package/dist/misc/contextualize.d.ts

@@ -0,0 +1,71 @@
+import type { Context, default as React } from 'react';
+/**
+ * The return type of {@linkcode contextualize}
+ *
+ * @see
+ * {@linkcode contextualize},
+ * {@linkcode ContextualizeWith}
+ */
+export type ContextualizePipe = {
+    with: ContextualizeWith;
+    end: () => React.JSX.Element;
+};
+/**
+ * @see
+ * {@linkcode contextualize},
+ * {@linkcode ContextualizePipe}
+ */
+export type ContextualizeWith = <T>(Context: Context<T>, value: NoInfer<T>) => ContextualizePipe;
+/**
+ * An alternative way to provide context values to component trees that avoids
+ * ever-increasing indentation
+ *
+ * A context-specific version of the more general {@linkcode 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();
+ * ```
+ *
+ * @param jsx The JSX to contextualize
+ *
+ * @returns 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
+ * {@linkcode ContextualizePipe}
+ */
+export declare function contextualize(jsx: React.JSX.Element): ContextualizePipe;
+//# sourceMappingURL=contextualize.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"contextualize.d.ts","sourceRoot":"","sources":["../../src/misc/contextualize.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,IAAI,KAAK,EAAE,MAAM,OAAO,CAAC;AAKvD;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,iBAAiB,CAAC;IACxB,GAAG,EAAE,MAAM,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC;CAC9B,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,EAChC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,KACd,iBAAiB,CAAC;AAEvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,OAAO,GAAG,iBAAiB,CAWvE"}

package/dist/misc/contextualize.js

@@ -0,0 +1,63 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * An alternative way to provide context values to component trees that avoids
+ * ever-increasing indentation
+ *
+ * A context-specific version of the more general {@linkcode 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();
+ * ```
+ *
+ * @param jsx The JSX to contextualize
+ *
+ * @returns 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
+ * {@linkcode ContextualizePipe}
+ */
+export function contextualize(jsx) {
+    return {
+        with(Context, value) {
+            return contextualize(_jsx(Context.Provider, { value: value, children: jsx }));
+        },
+        end() {
+            return jsx;
+        },
+    };
+}
+//# sourceMappingURL=contextualize.js.map

package/dist/misc/contextualize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextualize.js","sourceRoot":"","sources":["../../src/misc/contextualize.tsx"],"names":[],"mappings":";AA2BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,MAAM,UAAU,aAAa,CAAC,GAAsB;IAClD,OAAO;QACL,IAAI,CAAI,OAAmB,EAAE,KAAQ;YACnC,OAAO,aAAa,CAClB,KAAC,OAAO,CAAC,QAAQ,IAAC,KAAK,EAAE,KAAK,YAAG,GAAG,GAAoB,CACzD,CAAC;QACJ,CAAC;QACD,GAAG;YACD,OAAO,GAAG,CAAC;QACb,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/misc/createSafeContext.d.ts

@@ -18,7 +18,7 @@ import type { ArgumentFallback } from '../utils.js';
  *   Right,
  * }
  *
- * // Before
+ * // Before:
  * const DirectionContext = createContext<Direction | undefined>(undefined);
  * DirectionContext.displayName = 'DirectionContext';
  *
@@ -35,7 +35,7 @@ import type { ArgumentFallback } from '../utils.js';
  *   return direction;
  * };
  *
- * // After
+ * // After:
  * const { DirectionContext, useDirection } =
  *   createSafeContext<Direction>()('Direction'); // That's it :)
  *

package/dist/misc/createSafeContext.js

@@ -18,7 +18,7 @@ const moValueSymbol = Symbol('noValue');
  *   Right,
  * }
  *
- * // Before
+ * // Before:
  * const DirectionContext = createContext<Direction | undefined>(undefined);
  * DirectionContext.displayName = 'DirectionContext';
  *
@@ -35,7 +35,7 @@ const moValueSymbol = Symbol('noValue');
  *   return direction;
  * };
  *
- * // After
+ * // After:
  * const { DirectionContext, useDirection } =
  *   createSafeContext<Direction>()('Direction'); // That's it :)
  *

package/dist/misc/index.d.ts

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

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

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

package/dist/misc/index.js

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

package/dist/misc/index.js.map

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

package/dist/misc/wrapJSX.d.ts

@@ -0,0 +1,76 @@
+import type { ComponentProps, JSXElementConstructor, default as React } from 'react';
+/**
+ * The return type of {@linkcode wrapJSX}
+ *
+ * @see
+ * {@linkcode wrapJSX},
+ * {@linkcode WrapJSXWith}
+ */
+export type JSXWrapPipe = {
+    with: WrapJSXWith;
+    end: () => React.JSX.Element;
+};
+/**
+ * @see
+ * {@linkcode wrapJSX},
+ * {@linkcode JSXWrapPipe}
+ */
+export type WrapJSXWith = <C extends keyof JSX.IntrinsicElements | JSXElementConstructor<any>>(...args: [
+    Component: 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'>
+    ])
+]) => JSXWrapPipe;
+/**
+ * An alternative way to compose JSX that avoids ever-increasing indentation
+ *
+ * A more general version of the context-specific {@linkcode 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(),
+ * );
+ * ```
+ *
+ * @param jsx The JSX to wrap
+ *
+ * @returns 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
+ * {@linkcode JSXWrapPipe}
+ */
+export declare function wrapJSX(jsx: React.JSX.Element): JSXWrapPipe;
+//# sourceMappingURL=wrapJSX.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"wrapJSX.d.ts","sourceRoot":"","sources":["../../src/misc/wrapJSX.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,qBAAqB,EACrB,OAAO,IAAI,KAAK,EACjB,MAAM,OAAO,CAAC;AAKf;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,WAAW,CAAC;IAClB,GAAG,EAAE,MAAM,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC;CAC9B,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAErB,CAAC,CAAC,SAAS,MAAM,GAAG,CAAC,iBAAiB,GAAG,qBAAqB,CAAC,GAAG,CAAC,EACjE,GAAG,IAAI,EAAE;IACP,SAAS,EAAE,CAAC;IACZ,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,SAAS,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,GAClE;QACE,KAAK,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,mBAAmB,GACnC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC;KACtC,GACD;QACE,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,mBAAmB,GAClC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC;KACtC,CAAC;CACP,KACE,WAAW,CAAC;AAEnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,OAAO,GAAG,WAAW,CAc3D"}

package/dist/misc/wrapJSX.js

@@ -0,0 +1,61 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * An alternative way to compose JSX that avoids ever-increasing indentation
+ *
+ * A more general version of the context-specific {@linkcode 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(),
+ * );
+ * ```
+ *
+ * @param jsx The JSX to wrap
+ *
+ * @returns 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
+ * {@linkcode JSXWrapPipe}
+ */
+export function wrapJSX(jsx) {
+    return {
+        with(Component, props = {}) {
+            return wrapJSX(_jsx(Component, { ...props, children: jsx }));
+        },
+        end() {
+            return jsx;
+        },
+    };
+}
+//# sourceMappingURL=wrapJSX.js.map

package/dist/misc/wrapJSX.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrapJSX.js","sourceRoot":"","sources":["../../src/misc/wrapJSX.tsx"],"names":[],"mappings":";AA2CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,MAAM,UAAU,OAAO,CAAC,GAAsB;IAC5C,OAAO;QACL,IAAI,CACF,SAEiC,EACjC,QAAgB,EAAE;YAElB,OAAO,OAAO,CAAC,KAAC,SAAS,OAAK,KAAK,YAAG,GAAG,GAAa,CAAC,CAAC;QAC1D,CAAC;QACD,GAAG;YACD,OAAO,GAAG,CAAC;QACb,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aweebit/react-essentials",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "type": "module",
   "repository": "github:aweebit/react-essentials",
   "main": "dist/index.js",
@@ -10,7 +10,7 @@
     "prettier": "npm run prettier:base -- .",
     "lint": "eslint --max-warnings=0",
     "build": "rimraf dist && tsc -b -f",
-    "doc": "rimraf README.md && typedoc",
+    "doc": "rimraf README.md && typedoc && node scripts/fixReadmeLinks.js && npm run prettier:base -- README.md",
     "prepack": "npm run build && npm run doc",
     "prepare": "husky"
   },
@@ -29,6 +29,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.36.0",
+    "@types/node": "^22.18.6",
     "@types/react": "^18.3.24",
     "eslint": "^9.36.0",
     "eslint-config-prettier": "^10.1.8",

package/scripts/fixReadmeLinks.js

@@ -0,0 +1,23 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const rootDir = join(import.meta.dirname, '..');
+
+const headerPath = join(rootDir, 'README-header.md');
+const readmePath = join(rootDir, 'README.md');
+
+const header = await readFile(headerPath, 'utf8');
+const readme = await readFile(readmePath, 'utf8');
+
+const newReadme =
+  header +
+  readme
+    .slice(header.length)
+    .replaceAll(
+      /\(#useeventlistener((?:-1)?)\)/g,
+      (match, /** @type {string} */ suffix) => {
+        return `(#useeventlistener${suffix ? '' : '-1'})`;
+      },
+    );
+
+await writeFile(readmePath, newReadme);

package/src/misc/contextualize.tsx

@@ -0,0 +1,90 @@
+import type { Context, default as React } from 'react';
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import type { wrapJSX } from './wrapJSX.js';
+
+/**
+ * The return type of {@linkcode contextualize}
+ *
+ * @see
+ * {@linkcode contextualize},
+ * {@linkcode ContextualizeWith}
+ */
+export type ContextualizePipe = {
+  with: ContextualizeWith;
+  end: () => React.JSX.Element;
+};
+
+/**
+ * @see
+ * {@linkcode contextualize},
+ * {@linkcode ContextualizePipe}
+ */
+export type ContextualizeWith = <T>(
+  Context: Context<T>,
+  value: NoInfer<T>,
+) => ContextualizePipe;
+
+/**
+ * An alternative way to provide context values to component trees that avoids
+ * ever-increasing indentation
+ *
+ * A context-specific version of the more general {@linkcode 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();
+ * ```
+ *
+ * @param jsx The JSX to contextualize
+ *
+ * @returns 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
+ * {@linkcode ContextualizePipe}
+ */
+export function contextualize(jsx: React.JSX.Element): ContextualizePipe {
+  return {
+    with<T>(Context: Context<T>, value: T) {
+      return contextualize(
+        <Context.Provider value={value}>{jsx}</Context.Provider>,
+      );
+    },
+    end() {
+      return jsx;
+    },
+  };
+}

package/src/misc/createSafeContext.ts

@@ -21,7 +21,7 @@ const moValueSymbol = Symbol('noValue');
  *   Right,
  * }
  *
- * // Before
+ * // Before:
  * const DirectionContext = createContext<Direction | undefined>(undefined);
  * DirectionContext.displayName = 'DirectionContext';
  *
@@ -38,7 +38,7 @@ const moValueSymbol = Symbol('noValue');
  *   return direction;
  * };
  *
- * // After
+ * // After:
  * const { DirectionContext, useDirection } =
  *   createSafeContext<Direction>()('Direction'); // That's it :)
  *

package/src/misc/index.ts

@@ -1 +1,3 @@
+export * from './contextualize.js';
 export * from './createSafeContext.js';
+export * from './wrapJSX.js';

package/src/misc/wrapJSX.tsx

@@ -0,0 +1,107 @@
+import type {
+  ComponentProps,
+  JSXElementConstructor,
+  default as React,
+} from 'react';
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import type { contextualize } from './contextualize.js';
+
+/**
+ * The return type of {@linkcode wrapJSX}
+ *
+ * @see
+ * {@linkcode wrapJSX},
+ * {@linkcode WrapJSXWith}
+ */
+export type JSXWrapPipe = {
+  with: WrapJSXWith;
+  end: () => React.JSX.Element;
+};
+
+/**
+ * @see
+ * {@linkcode wrapJSX},
+ * {@linkcode JSXWrapPipe}
+ */
+export type WrapJSXWith =
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  <C extends keyof JSX.IntrinsicElements | JSXElementConstructor<any>>(
+    ...args: [
+      Component: 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'>,
+          ]),
+    ]
+  ) => JSXWrapPipe;
+
+/**
+ * An alternative way to compose JSX that avoids ever-increasing indentation
+ *
+ * A more general version of the context-specific {@linkcode 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(),
+ * );
+ * ```
+ *
+ * @param jsx The JSX to wrap
+ *
+ * @returns 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
+ * {@linkcode JSXWrapPipe}
+ */
+export function wrapJSX(jsx: React.JSX.Element): JSXWrapPipe {
+  return {
+    with(
+      Component:
+        | keyof React.JSX.IntrinsicElements
+        | JSXElementConstructor<object>,
+      props: object = {},
+    ) {
+      return wrapJSX(<Component {...props}>{jsx}</Component>);
+    },
+    end() {
+      return jsx;
+    },
+  };
+}