@aweebit/react-essentials 0.9.0 → 0.10.1

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

@@ -1,33 +1,5 @@
-import { type Context, type Provider } from 'react';
+import { type Context } from 'react';
 import type { ArgumentFallback } from '../utils.js';
-/**
- * The return type of {@linkcode createSafeContext}
- *
- * @see
- * {@linkcode createSafeContext},
- * {@linkcode RestrictedContext}
- */
-export type SafeContext<DisplayName extends string, T> = {
-    [K in `${DisplayName}Context`]: RestrictedContext<T>;
-} & {
-    [K in `use${DisplayName}`]: () => T;
-};
-/**
- * A React context with a required `displayName` and the obsolete `Consumer`
- * property purposefully omitted so that it is impossible to pass the context
- * as an argument to `useContext` or `use` (the hook produced with
- * {@linkcode createSafeContext} should be used instead)
- *
- * @see
- * {@linkcode createSafeContext}
- */
-export type RestrictedContext<T> = Context<T> extends Provider<T> ? {
-    Provider: Provider<T>;
-    displayName: string;
-} & Provider<T> : {
-    Provider: Provider<T>;
-    displayName: string;
-};
 /**
  * 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,
@@ -46,7 +18,7 @@ export type RestrictedContext<T> = Context<T> extends Provider<T> ? {
  *   Right,
  * }
  *
- * // Before
+ * // Before:
  * const DirectionContext = createContext<Direction | undefined>(undefined);
  * DirectionContext.displayName = 'DirectionContext';
  *
@@ -63,7 +35,7 @@ export type RestrictedContext<T> = Context<T> extends Provider<T> ? {
  *   return direction;
  * };
  *
- * // After
+ * // After:
  * const { DirectionContext, useDirection } =
  *   createSafeContext<Direction>()('Direction'); // That's it :)
  *
@@ -83,9 +55,6 @@ export type RestrictedContext<T> = Context<T> extends Provider<T> ? {
  * - ``` `${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
- *
- * @see
- * {@linkcode SafeContext}
  */
-export declare function createSafeContext<T = never>(): <DisplayName extends string>(displayName: [T] extends [never] ? never : ArgumentFallback<DisplayName, never, string>) => SafeContext<DisplayName, T>;
+export declare function createSafeContext<T = never>(): <DisplayName extends string>(displayName: [T] extends [never] ? never : ArgumentFallback<DisplayName, never, string>) => { [K in `${DisplayName}Context`]: Context<T>; } & { [K in `use${DisplayName}`]: () => T; };
 //# sourceMappingURL=createSafeContext.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"createSafeContext.d.ts","sourceRoot":"","sources":["../../src/misc/createSafeContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,QAAQ,EAA6B,MAAM,OAAO,CAAC;AAC/E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAIpD;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,CAAC,WAAW,SAAS,MAAM,EAAE,CAAC,IAAI;KACtD,CAAC,IAAI,GAAG,WAAW,SAAS,GAAG,iBAAiB,CAAC,CAAC,CAAC;CACrD,GAAG;KACD,CAAC,IAAI,MAAM,WAAW,EAAE,GAAG,MAAM,CAAC;CACpC,CAAC;AAEF;;;;;;;;GAQG;AAIH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAC7B,OAAO,CAAC,CAAC,CAAC,SAAS,QAAQ,CAAC,CAAC,CAAC,GAC1B;IAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,QAAQ,CAAC,CAAC,CAAC,GAC5D;IAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,GAAG,KAAK,MACjC,WAAW,SAAS,MAAM,EAChC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAC5B,KAAK,GACL,gBAAgB,CAAC,WAAW,EAAE,KAAK,EAAE,MAAM,CAAC,KAC/C,WAAW,CAAC,WAAW,EAAE,CAAC,CAAC,CAsB/B"}
+{"version":3,"file":"createSafeContext.d.ts","sourceRoot":"","sources":["../../src/misc/createSafeContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAA6B,MAAM,OAAO,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAIpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,GAAG,KAAK,MACjC,WAAW,SAAS,MAAM,EAChC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAC5B,KAAK,GACL,gBAAgB,CAAC,WAAW,EAAE,KAAK,EAAE,MAAM,CAAC,KAC/C,GAAG,CAAC,IAAI,GAAG,WAAW,SAAS,GAAG,OAAO,CAAC,CAAC,CAAC,GAAE,GAAG,GACjD,CAAC,IAAI,MAAM,WAAW,EAAE,GAAG,MAAM,CAAC,GACpC,CAsBF"}

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 :)
  *
@@ -55,9 +55,6 @@ const moValueSymbol = Symbol('noValue');
  * - ``` `${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
- *
- * @see
- * {@linkcode SafeContext}
  */
 export function createSafeContext() {
     return (displayName) => {

package/dist/misc/createSafeContext.js.map

@@ -1 +1 @@
-{"version":3,"file":"createSafeContext.js","sourceRoot":"","sources":["../../src/misc/createSafeContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+B,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAG/E,MAAM,aAAa,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;AAgCxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,CACL,WAEgD,EACnB,EAAE;QAC/B,MAAM,WAAW,GAAG,GAAG,WAA0B,SAAkB,CAAC;QACpE,MAAM,QAAQ,GAAG,MAAM,WAA0B,EAAW,CAAC;QAE7D,MAAM,OAAO,GAAG,aAAa,CAA2B,aAAa,CAAC,CAAC;QACvE,OAAO,CAAC,WAAW,GAAG,WAAW,CAAC;QAElC,OAAO;YACL,CAAC,WAAW,CAAC,EAAE,OAA+B;YAC9C,CAAC,QAAQ,CAAC,EAAE,GAAG,EAAE;gBACf,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;gBAClC,IAAI,KAAK,KAAK,aAAa,EAAE,CAAC;oBAC5B,MAAM,IAAI,KAAK,CAAC,MAAM,WAAW,qBAAqB,CAAC,CAAC;gBAC1D,CAAC;gBACD,OAAO,KAAK,CAAC;YACf,CAAC;SAKF,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"createSafeContext.js","sourceRoot":"","sources":["../../src/misc/createSafeContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAGhE,MAAM,aAAa,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,CACL,WAEgD,EAGhD,EAAE;QACF,MAAM,WAAW,GAAG,GAAG,WAA0B,SAAkB,CAAC;QACpE,MAAM,QAAQ,GAAG,MAAM,WAA0B,EAAW,CAAC;QAE7D,MAAM,OAAO,GAAG,aAAa,CAA2B,aAAa,CAAC,CAAC;QACvE,OAAO,CAAC,WAAW,GAAG,WAAW,CAAC;QAElC,OAAO;YACL,CAAC,WAAW,CAAC,EAAE,OAAqB;YACpC,CAAC,QAAQ,CAAC,EAAE,GAAG,EAAE;gBACf,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;gBAClC,IAAI,KAAK,KAAK,aAAa,EAAE,CAAC;oBAC5B,MAAM,IAAI,KAAK,CAAC,MAAM,WAAW,qBAAqB,CAAC,CAAC;gBAC1D,CAAC;gBACD,OAAO,KAAK,CAAC;YACf,CAAC;SAKF,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC"}

package/dist/misc/index.d.ts

@@ -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.9.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

@@ -1,38 +1,8 @@
-import { type Context, type Provider, createContext, useContext } from 'react';
+import { type Context, createContext, useContext } from 'react';
 import type { ArgumentFallback } from '../utils.js';
 
 const moValueSymbol = Symbol('noValue');
 
-/**
- * The return type of {@linkcode createSafeContext}
- *
- * @see
- * {@linkcode createSafeContext},
- * {@linkcode RestrictedContext}
- */
-export type SafeContext<DisplayName extends string, T> = {
-  [K in `${DisplayName}Context`]: RestrictedContext<T>;
-} & {
-  [K in `use${DisplayName}`]: () => T;
-};
-
-/**
- * A React context with a required `displayName` and the obsolete `Consumer`
- * property purposefully omitted so that it is impossible to pass the context
- * as an argument to `useContext` or `use` (the hook produced with
- * {@linkcode createSafeContext} should be used instead)
- *
- * @see
- * {@linkcode createSafeContext}
- */
-// The type is conditional so that both React 18 and 19 are correctly supported.
-// The code duplication is necessary for the type to be displayed correctly by
-// TypeDoc.
-export type RestrictedContext<T> =
-  Context<T> extends Provider<T>
-    ? { Provider: Provider<T>; displayName: string } & Provider<T>
-    : { Provider: Provider<T>; displayName: string };
-
 /**
  * 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,
@@ -51,7 +21,7 @@ export type RestrictedContext<T> =
  *   Right,
  * }
  *
- * // Before
+ * // Before:
  * const DirectionContext = createContext<Direction | undefined>(undefined);
  * DirectionContext.displayName = 'DirectionContext';
  *
@@ -68,7 +38,7 @@ export type RestrictedContext<T> =
  *   return direction;
  * };
  *
- * // After
+ * // After:
  * const { DirectionContext, useDirection } =
  *   createSafeContext<Direction>()('Direction'); // That's it :)
  *
@@ -88,16 +58,15 @@ export type RestrictedContext<T> =
  * - ``` `${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
- *
- * @see
- * {@linkcode SafeContext}
  */
 export function createSafeContext<T = never>() {
   return <DisplayName extends string>(
     displayName: [T] extends [never]
       ? never
       : ArgumentFallback<DisplayName, never, string>,
-  ): SafeContext<DisplayName, T> => {
+  ): { [K in `${DisplayName}Context`]: Context<T> } & {
+    [K in `use${DisplayName}`]: () => T;
+  } => {
     const contextName = `${displayName as DisplayName}Context` as const;
     const hookName = `use${displayName as DisplayName}` as const;
 
@@ -105,7 +74,7 @@ export function createSafeContext<T = never>() {
     Context.displayName = contextName;
 
     return {
-      [contextName]: Context as RestrictedContext<T>,
+      [contextName]: Context as Context<T>,
       [hookName]: () => {
         const value = useContext(Context);
         if (value === moValueSymbol) {
@@ -114,7 +83,7 @@ export function createSafeContext<T = never>() {
         return value;
       },
     } as {
-      [K in typeof contextName]: RestrictedContext<T>;
+      [K in typeof contextName]: Context<T>;
     } & {
       [K in typeof hookName]: () => T;
     };

package/src/misc/index.ts

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