@aweebit/react-essentials 0.5.3 → 0.6.0

package/src/misc/createSafeContext.ts

@@ -0,0 +1,83 @@
+import { type Context, type Provider, createContext, useContext } from 'react';
+import type { ArgumentFallback } from '../utils.js';
+
+const moValueSymbol = Symbol('noValue');
+
+/**
+ * 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 };
+
+/**
+ * @see {@linkcode createSafeContext}
+ */
+export type SafeContext<DisplayName extends string, T> = {
+  [K in `${DisplayName}Context`]: RestrictedContext<T>;
+} & {
+  [K in `use${DisplayName}`]: () => T;
+};
+
+/**
+ * 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
+ *
+ * @example
+ * ```tsx
+ * const { ItemsContext, useItems } = createSafeContext<string[]>()('Items');
+ *
+ * const Parent = () => (
+ *   <ItemsContext value={['compass', 'newspaper', 'banana']}>
+ *     <Child />
+ *   </ItemsContext>
+ * );
+ *
+ * const Child = () => useItems().join(', ');
+ * ```
+ *
+ * @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
+ *   current context value if one was provided, or throws an error otherwise
+ */
+export function createSafeContext<T = never>() {
+  return <DisplayName extends string>(
+    displayName: [T] extends [never]
+      ? never
+      : ArgumentFallback<DisplayName, never, string>,
+  ): SafeContext<DisplayName, T> => {
+    const contextName = `${displayName as DisplayName}Context` as const;
+    const hookName = `use${displayName as DisplayName}` as const;
+
+    const Context = createContext<T | typeof moValueSymbol>(moValueSymbol);
+    Context.displayName = contextName;
+
+    return {
+      [contextName]: Context as RestrictedContext<T>,
+      [hookName]: () => {
+        const value = useContext(Context);
+        if (value === moValueSymbol) {
+          throw new Error(`No ${contextName} value was provided`);
+        }
+        return value;
+      },
+    } as {
+      [K in typeof contextName]: RestrictedContext<T>;
+    } & {
+      [K in typeof hookName]: () => T;
+    };
+  };
+}

package/src/misc/index.ts

@@ -0,0 +1 @@
+export * from './createSafeContext.js';

package/src/utils.ts

@@ -0,0 +1,25 @@
+import type { DependencyList } from 'react';
+
+export type Callable = (...args: never) => unknown;
+
+export type ArgumentFallback<
+  T extends Base,
+  Default extends Base,
+  Base = unknown,
+> = [T] extends [never] ? Default : [Base] extends [T] ? Default : T;
+
+export function noop() {}
+
+export function isFunction(input: unknown): input is Callable {
+  return typeof input === 'function';
+}
+
+export function depsAreEqual(
+  prevDeps: DependencyList,
+  deps: DependencyList,
+): boolean {
+  return (
+    prevDeps.length === deps.length &&
+    deps.every((dep, index) => Object.is(dep, prevDeps[index]))
+  );
+}

package/dist/utils/index.d.ts

@@ -1,4 +0,0 @@
-import type { DependencyList } from 'react';
-export declare function isFunction(input: unknown): input is Function;
-export declare function depsAreEqual(prevDeps: DependencyList, deps: DependencyList): boolean;
-//# sourceMappingURL=index.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AAG5C,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D;AAED,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,cAAc,EACxB,IAAI,EAAE,cAAc,GACnB,OAAO,CAKT"}

package/dist/utils/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../lib/utils/index.ts"],"names":[],"mappings":"AAEA,sEAAsE;AACtE,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,OAAO,KAAK,KAAK,UAAU,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,QAAwB,EACxB,IAAoB;IAEpB,OAAO,CACL,QAAQ,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM;QAC/B,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAC5D,CAAC;AACJ,CAAC"}

package/lib/hooks/useEventListener.ts

@@ -1,95 +0,0 @@
-/**
- * @file Based on {@link https://github.com/juliencrn/usehooks-ts}
- *
- * @license MIT
- * @copyright 2020 Julien CARON
- */
-
-import { useEffect, useLayoutEffect, useRef } from 'react';
-
-/**
- * Adds `handler` as a listener for the event `eventName` of `element`
- * (or `window` by default) with the provided `options` applied
- *
- * It is the user's responsibility to make sure `element` and `options` values
- * are correctly memoized!
- */
-
-// SVGElement Event based useEventListener interface
-function useEventListener<
-  K extends keyof SVGElementEventMap,
-  T extends SVGElement,
->(
-  eventName: K,
-  handler: (this: T, event: SVGElementEventMap[K]) => void,
-  element: T,
-  options?: boolean | AddEventListenerOptions,
-): void;
-
-// HTMLElement Event based useEventListener interface
-function useEventListener<
-  K extends keyof HTMLElementEventMap,
-  T extends HTMLElement,
->(
-  eventName: K,
-  handler: (this: T, event: HTMLElementEventMap[K]) => void,
-  element: T,
-  options?: boolean | AddEventListenerOptions,
-): void;
-
-// Document Event based useEventListener interface
-function useEventListener<K extends keyof DocumentEventMap>(
-  eventName: K,
-  handler: (this: Document, event: DocumentEventMap[K]) => void,
-  element: Document,
-  options?: boolean | AddEventListenerOptions,
-): void;
-
-// Window Event based useEventListener interface
-function useEventListener<K extends keyof WindowEventMap>(
-  eventName: K,
-  handler: (this: Window, event: WindowEventMap[K]) => void,
-  element?: Window,
-  options?: boolean | AddEventListenerOptions,
-): void;
-
-// Fallback overload for all other event targets and types
-function useEventListener(
-  eventName: string,
-  handler: (this: EventTarget, event: Event) => void,
-  element?: EventTarget,
-  options?: boolean | AddEventListenerOptions,
-): void;
-
-function useEventListener(
-  eventName: string,
-  handler: (this: EventTarget, event: Event) => void,
-  element?: EventTarget,
-  options?: boolean | AddEventListenerOptions,
-) {
-  // Create a ref that stores handler
-  const savedHandler = useRef(handler);
-
-  useLayoutEffect(() => {
-    savedHandler.current = handler;
-  }, [handler]);
-
-  useEffect(() => {
-    // Define the listening target
-    const targetElement = element ?? window;
-
-    // Create event listener that calls handler function stored in ref
-    const listener: typeof handler = function (event) {
-      savedHandler.current.call(this, event);
-    };
-
-    targetElement.addEventListener(eventName, listener, options);
-
-    // Remove event listener on cleanup
-    return () => {
-      targetElement.removeEventListener(eventName, listener, options);
-    };
-  }, [eventName, element, options]);
-}
-
-export default useEventListener;

package/lib/index.ts

@@ -1,4 +0,0 @@
-export { default as useEventListener } from './hooks/useEventListener.js';
-export { default as useForceUpdate } from './hooks/useForceUpdate.js';
-export { default as useReducerWithDeps } from './hooks/useReducerWithDeps.js';
-export { default as useStateWithDeps } from './hooks/useStateWithDeps.js';

package/lib/utils/index.ts

@@ -1,16 +0,0 @@
-import type { DependencyList } from 'react';
-
-// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
-export function isFunction(input: unknown): input is Function {
-  return typeof input === 'function';
-}
-
-export function depsAreEqual(
-  prevDeps: DependencyList,
-  deps: DependencyList,
-): boolean {
-  return (
-    prevDeps.length === deps.length &&
-    deps.every((dep, index) => Object.is(dep, prevDeps[index]))
-  );
-}