@aweebit/react-essentials 0.6.0 → 0.8.0

package/src/misc/createSafeContext.ts

@@ -9,7 +9,8 @@ const moValueSymbol = Symbol('noValue');
  * as an argument to `useContext` or `use` (the hook produced with
  * {@linkcode createSafeContext} should be used instead)
  *
- * @see {@linkcode createSafeContext}
+ * @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
@@ -20,7 +21,11 @@ export type RestrictedContext<T> =
     : { Provider: Provider<T>; displayName: string };
 
 /**
- * @see {@linkcode createSafeContext}
+ * The return type of {@linkcode createSafeContext}
+ *
+ * @see
+ * {@linkcode createSafeContext},
+ * {@linkcode RestrictedContext}
  */
 export type SafeContext<DisplayName extends string, T> = {
   [K in `${DisplayName}Context`]: RestrictedContext<T>;
@@ -33,25 +38,59 @@ export type SafeContext<DisplayName extends string, T> = {
  * 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()]}`;
  * ```
  *
  * @returns
  * A function that accepts a single string argument `displayName` (e.g.
- * `"Items"`) 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
+ * `"Direction"`) and returns an object with the following properties:
+ * - ``` `${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>(