@aweebit/react-essentials 0.7.0 → 0.8.1

package/dist/utils.js

@@ -1,7 +1,3 @@
-export function noop() { }
-export function isFunction(input) {
-    return typeof input === 'function';
-}
 export function depsAreEqual(prevDeps, deps) {
     return (prevDeps.length === deps.length &&
         deps.every((dep, index) => Object.is(dep, prevDeps[index])));

package/dist/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAUA,MAAM,UAAU,IAAI,KAAI,CAAC;AAEzB,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"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAQA,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aweebit/react-essentials",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "type": "module",
   "repository": "github:aweebit/react-essentials",
   "main": "dist/index.js",

package/src/hooks/useEventListener.ts

@@ -1,121 +1,114 @@
-/**
- * @file Based on {@link https://github.com/juliencrn/usehooks-ts}
- *
- * @license MIT
- * @copyright 2020 Julien CARON
- */
-
-import { useEffect, useMemo, useRef } from 'react';
-
-type UseEventListenerOverloadArgs<
-  EventMap,
-  K extends keyof EventMap,
-  T extends EventTarget,
-> = [
-  target: T | null,
-  eventName: K,
-  handler: (this: NoInfer<T>, event: EventMap[K]) => void,
-  options?: AddEventListenerOptions | boolean,
-];
+import { useEffect, useMemo, useRef, type RefObject } from 'react';
 
 /**
- * Adds `handler` as a listener for the event `eventName` of `target` with the
- * provided `options` applied
+ * The type of {@linkcode useEventListener}
  *
- * If `target` is not provided, `window` is used instead.
- *
- * If `target` is `null`, no event listener is added. This is useful when
- * working with DOM element refs, or when the event listener needs to be removed
- * temporarily.
- *
- * @example
- * ```tsx
- * useEventListener('resize', () => {
- *   console.log(window.innerWidth, window.innerHeight);
- * });
- *
- * useEventListener(document, 'visibilitychange', () => {
- *   console.log(document.visibilityState);
- * });
- *
- * const buttonRef = useRef<HTMLButtonElement>(null);
- * useEventListener(buttonRef.current, 'click', () => console.log('click'));
- * ```
- *
- * @ignore
+ * @see
+ * {@linkcode useEventListener},
+ * {@linkcode UseEventListenerWithImplicitWindowTarget},
+ * {@linkcode UseEventListenerWithExplicitGlobalTarget},
+ * {@linkcode UseEventListenerWithAnyExplicitTarget}
  */
-export function useEventListener<K extends keyof WindowEventMap>(
-  eventName: K,
-  handler: (this: Window, event: WindowEventMap[K]) => void,
-  options?: AddEventListenerOptions | boolean,
-): void;
+export type UseEventListener = UseEventListenerWithImplicitWindowTarget &
+  UseEventListenerWithExplicitGlobalTarget &
+  UseEventListenerWithAnyExplicitTarget;
 
 /**
- * @see {@linkcode useEventListener}
- * @ignore
+ * @see
+ * {@linkcode useEventListener},
+ * {@linkcode UseEventListenerWithImplicitWindowTargetArgs}
  */
-export function useEventListener<K extends keyof WindowEventMap>(
-  ...args: UseEventListenerOverloadArgs<WindowEventMap, K, Window>
-): void;
+export type UseEventListenerWithImplicitWindowTarget = <
+  K extends keyof WindowEventMap,
+>(
+  ...args: UseEventListenerWithImplicitWindowTargetArgs<K>
+) => void;
 
 /**
- * @see {@linkcode useEventListener}
- * @ignore
+ * @see
+ * {@linkcode useEventListener},
+ * {@linkcode UseEventListenerWithExplicitTarget}
  */
-export function useEventListener<K extends keyof DocumentEventMap>(
-  ...args: UseEventListenerOverloadArgs<DocumentEventMap, K, Document>
-): void;
+export type UseEventListenerWithExplicitGlobalTarget =
+  UseEventListenerWithExplicitTarget<Window, WindowEventMap> &
+    UseEventListenerWithExplicitTarget<Document, DocumentEventMap> &
+    UseEventListenerWithExplicitTarget<HTMLElement, HTMLElementEventMap> &
+    UseEventListenerWithExplicitTarget<SVGElement, SVGElementEventMap> &
+    UseEventListenerWithExplicitTarget<MathMLElement, MathMLElementEventMap>;
 
 /**
- * @see {@linkcode useEventListener}
- * @ignore
+ * @see
+ * {@linkcode useEventListener},
+ * {@linkcode UseEventListenerWithExplicitTargetArgs}
  */
-export function useEventListener<
-  K extends keyof HTMLElementEventMap,
-  T extends HTMLElement,
->(...args: UseEventListenerOverloadArgs<HTMLElementEventMap, K, T>): void;
+export type UseEventListenerWithExplicitTarget<
+  Target extends EventTarget,
+  EventMap = Record<string, Event>,
+> = <T extends Target, K extends keyof EventMap>(
+  ...args: UseEventListenerWithExplicitTargetArgs<EventMap, T, K>
+) => void;
 
 /**
- * @see {@linkcode useEventListener}
- * @ignore
+ * @see
+ * {@linkcode useEventListener},
+ * {@linkcode UseEventListenerWithExplicitTarget}
  */
-export function useEventListener<
-  K extends keyof SVGElementEventMap,
-  T extends SVGElement,
->(...args: UseEventListenerOverloadArgs<SVGElementEventMap, K, T>): void;
+export type UseEventListenerWithAnyExplicitTarget =
+  UseEventListenerWithExplicitTarget<EventTarget>;
 
 /**
- * @see {@linkcode useEventListener}
- * @ignore
+ * @see
+ * {@linkcode useEventListener},
+ * {@linkcode UseEventListenerWithExplicitTargetArgs}
  */
-export function useEventListener<
-  K extends keyof MathMLElementEventMap,
-  T extends MathMLElement,
->(...args: UseEventListenerOverloadArgs<MathMLElementEventMap, K, T>): void;
+export type UseEventListenerWithImplicitWindowTargetArgs<
+  K extends keyof WindowEventMap,
+> =
+  UseEventListenerWithExplicitTargetArgs<WindowEventMap, Window, K> extends [
+    unknown,
+    ...infer Args,
+  ]
+    ? Args
+    : never;
 
 /**
- * @see {@linkcode useEventListener}
+ * @see
+ * {@linkcode useEventListener}
  */
-export function useEventListener<K extends keyof WindowEventMap>(
+export type UseEventListenerWithExplicitTargetArgs<
+  EventMap,
+  T extends EventTarget,
+  K extends keyof EventMap,
+> = [
+  target: T | (RefObject<T> & { addEventListener?: never }) | null,
   eventName: K,
-  handler: (this: Window, event: WindowEventMap[K]) => void,
-  options?: AddEventListenerOptions | boolean,
-): void;
+  handler: (this: NoInfer<T>, event: EventMap[K]) => void,
+  options?: AddEventListenerOptions | boolean | undefined,
+];
 
-/**
- * @see {@linkcode useEventListener}
- */
-export function useEventListener<T extends EventTarget>(
-  target: T | null,
-  eventName: string,
-  handler: (this: NoInfer<T>, event: Event) => void,
-  options?: AddEventListenerOptions | boolean,
-): void;
+type UseEventListenerWithImplicitWindowTargetArgsAny =
+  UseEventListenerWithImplicitWindowTargetArgs<keyof WindowEventMap>;
+
+type UseEventListenerWithExplicitTargetArgsAny =
+  UseEventListenerWithExplicitTargetArgs<
+    Record<string, Event>,
+    EventTarget,
+    string
+  >;
 
 /**
  * Adds `handler` as a listener for the event `eventName` of `target` with the
  * provided `options` applied
  *
+ * The following call signatures are available:
+ *
+ * ```ts
+ * function useEventListener(eventName, handler, options?): void;
+ * function useEventListener(target, eventName, handler, options?): void;
+ * ```
+ *
+ * For the full definition of the hook's type, see {@linkcode UseEventListener}.
+ *
  * If `target` is not provided, `window` is used instead.
  *
  * If `target` is `null`, no event listener is added. This is useful when
@@ -133,26 +126,34 @@ export function useEventListener<T extends EventTarget>(
  * });
  *
  * const buttonRef = useRef<HTMLButtonElement>(null);
- * useEventListener(buttonRef.current, 'click', () => console.log('click'));
+ * useEventListener(buttonRef, 'click', () => console.log('click'));
  * ```
+ *
+ * @see
+ * {@linkcode UseEventListener}
  */
-export function useEventListener(
-  ...args: UseEventListenerArgsWithoutTarget | UseEventListenerArgsWithTarget
+export const useEventListener: UseEventListener = function useEventListener(
+  ...args:
+    | UseEventListenerWithImplicitWindowTargetArgsAny
+    | UseEventListenerWithExplicitTargetArgsAny
 ) {
-  let eventName: string;
-  let handler: (this: EventTarget, event: Event) => void;
-  let target: EventTarget | null | undefined;
-  let options: AddEventListenerOptions | boolean | undefined;
-
-  if (typeof args[0] === 'string') {
-    [eventName, handler, options] = args as UseEventListenerArgsWithoutTarget;
-  } else {
-    [target, eventName, handler, options] =
-      args as UseEventListenerArgsWithTarget;
-  }
+  const [target, eventName, handler, options]: [
+    target: EventTarget | RefObject<EventTarget> | null,
+    eventName: string,
+    handler: (this: never, event: Event) => void,
+    options?: AddEventListenerOptions | boolean | undefined,
+  ] =
+    typeof args[0] === 'string'
+      ? [window, ...(args as UseEventListenerWithImplicitWindowTargetArgsAny)]
+      : (args as UseEventListenerWithExplicitTargetArgsAny);
+
+  const unwrappedTarget =
+    target && !('addEventListener' in target) ? target.current : target;
 
   const handlerRef = useRef(handler);
-  handlerRef.current = handler;
+  useEffect(() => {
+    handlerRef.current = handler;
+  }, [handler]);
 
   const {
     capture = false,
@@ -168,34 +169,19 @@ export function useEventListener(
   );
 
   useEffect(() => {
-    if (target === null) {
+    if (unwrappedTarget === null) {
       // No element has been attached to the ref yet
       return;
     }
 
-    const definedTarget = target ?? window;
-
     const listener: typeof handler = function (event) {
       handlerRef.current.call(this, event);
     };
 
-    definedTarget.addEventListener(eventName, listener, memoizedOptions);
+    unwrappedTarget.addEventListener(eventName, listener, memoizedOptions);
 
     return () => {
-      definedTarget.removeEventListener(eventName, listener, memoizedOptions);
+      unwrappedTarget.removeEventListener(eventName, listener, memoizedOptions);
     };
-  }, [eventName, target, memoizedOptions]);
-}
-
-type UseEventListenerArgsWithoutTarget = [
-  eventName: string,
-  handler: (event: Event) => void,
-  options?: AddEventListenerOptions | boolean | undefined,
-];
-
-type UseEventListenerArgsWithTarget = [
-  target: EventTarget | null,
-  eventName: string,
-  handler: (event: Event) => void,
-  options?: AddEventListenerOptions | boolean | undefined,
-];
+  }, [unwrappedTarget, eventName, memoizedOptions]);
+} as UseEventListener;

package/src/hooks/useForceUpdate.ts

@@ -11,54 +11,10 @@ import type { useReducerWithDeps } from './useReducerWithDeps.js';
  * This hook is designed in the most general way possible in order to cover all
  * imaginable use cases.
  *
- * @example
- * Sometimes, React's immutability constraints mean too much unnecessary copying
- * of data when new data arrives at a high frequency. In such cases, it might be
- * desirable to ignore the constraints by embracing imperative patterns.
- * Here is an example of a scenario where that can make sense:
- *
- * ```tsx
- * type SensorData = { timestamp: number; value: number };
- * const sensorDataRef = useRef<SensorData[]>([]);
- * const mostRecentSensorDataTimestampRef = useRef<number>(0);
- *
- * const [forceUpdate, updateCount] = useForceUpdate();
- * // Limiting the frequency of forced re-renders with some throttle function:
- * const throttledForceUpdateRef = useRef(throttle(forceUpdate));
- *
- * useEffect(() => {
- *   return sensorDataObservable.subscribe((data: SensorData) => {
- *     // Imagine new sensor data arrives every 1 millisecond. If we were following
- *     // React's immutability rules by creating a new array every time, the data
- *     // that's already there would have to be copied many times before the new
- *     // data would even get a chance to be reflected in the UI for the first time
- *     // because it typically takes much longer than 1 millisecond for a new frame
- *     // to be displayed. To prevent the waste of computational resources, we just
- *     // mutate the existing array every time instead:
- *     sensorDataRef.current.push(data);
- *     if (data.timestamp > mostRecentSensorDataTimestampRef.current) {
- *       mostRecentSensorDataTimestampRef.current = data.timestamp;
- *     }
- *     throttledForceUpdateRef.current();
- *   });
- * }, []);
- *
- * const [timeWindow, setTimeWindow] = useState(1000);
- * const selectedSensorData = useMemo(
- *   () => {
- *     // Keep this line if you don't want to disable the
- *     // react-hooks/exhaustive-deps ESLint rule:
- *     updateCount;
- *     const threshold = mostRecentSensorDataTimestampRef.current - timeWindow;
- *     return sensorDataRef.current.filter(
- *       ({ timestamp }) => timestamp >= threshold,
- *     );
- *   },
- *   // sensorDataRef.current always references the same array, so listing it as a
- *   // dependency is pointless. Instead, updateCount should be used:
- *   [updateCount, timeWindow],
- * );
- * ```
+ * @deprecated
+ * This hook encourages patterns that are unsafe in Concurrent React.
+ * For details and ideas on how to get rid of it, please check the discussion at
+ * https://www.reddit.com/r/react/comments/1nqcsri/comment/ng76cv5/.
  *
  * @param callback An optional callback function to call during renders that
  * were triggered with `forceUpdate()`

package/src/hooks/useReducerWithDeps.ts

@@ -1,4 +1,4 @@
-import { type DependencyList, useCallback, useRef } from 'react';
+import { type DependencyList, useRef } from 'react';
 import { useStateWithDeps } from './useStateWithDeps.js';
 
 // We cannot simply import the following types from @types/react since they are
@@ -18,6 +18,13 @@ export type ActionDispatch<ActionArg extends AnyActionArg> = (
  * `useReducer` hook with an additional dependency array `deps` that resets the
  * state to `initialState` when dependencies change
  *
+ * This hook is the reducer pattern counterpart of {@linkcode useStateWithDeps}.
+ *
+ * Due to React's limitations, a change in dependencies always causes two
+ * renders when using this hook. The result of the first render is thrown away
+ * as described in
+ * [useState > Storing information from previous renders](https://react.dev/reference/react/useState#storing-information-from-previous-renders).
+ *
  * For motivation and examples, see
  * https://github.com/facebook/react/issues/33041.
  *
@@ -60,9 +67,9 @@ export function useReducerWithDeps<S, A extends AnyActionArg>(
   // Only the initially provided reducer is used
   const reducerRef = useRef(reducer);
 
-  const dispatch = useCallback(function dispatch(...args: A): void {
+  function dispatch(...args: A): void {
     setState((previousState) => reducerRef.current(previousState, ...args));
-  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+  }
 
-  return [state, dispatch];
+  return [state, useRef(dispatch).current];
 }

package/src/hooks/useStateWithDeps.ts

@@ -1,24 +1,20 @@
-/**
- * @file Based on {@link https://github.com/peterjuras/use-state-with-deps}
- *
- * @license MIT
- * @copyright 2020 Peter Juras
- */
-
 import {
-  useCallback,
-  useRef,
+  useState,
   type DependencyList,
   type Dispatch,
   type SetStateAction,
 } from 'react';
-import { depsAreEqual, isFunction } from '../utils.js';
-import { useForceUpdate } from './useForceUpdate.js';
+import { depsAreEqual } from '../utils.js';
 
 /**
  * `useState` hook with an additional dependency array `deps` that resets the
  * state to `initialState` when dependencies change
  *
+ * Due to React's limitations, a change in dependencies always causes two
+ * renders when using this hook. The result of the first render is thrown away
+ * as described in
+ * [useState > Storing information from previous renders](https://react.dev/reference/react/useState#storing-information-from-previous-renders).
+ *
  * For motivation and more examples, see
  * https://github.com/facebook/react/issues/33041.
  *
@@ -37,7 +33,7 @@ import { useForceUpdate } from './useForceUpdate.js';
  *   evening: ['board games', 'dinner'],
  * };
  *
- * export function Example() {
+ * function Example() {
  *   const [timeOfDay, setTimeOfDay] = useState<TimeOfDay>('morning');
  *
  *   const activityOptions = activityOptionsByTimeOfDay[timeOfDay];
@@ -67,45 +63,14 @@ export function useStateWithDeps<S>(
   initialState: S | ((previousState?: S) => S),
   deps: DependencyList,
 ): [S, Dispatch<SetStateAction<S>>] {
-  // It would be possible to use useState instead of useRef to store the state,
-  // however this would trigger re-renders whenever the state is reset due to a
-  // change in dependencies. In order to avoid these re-renders, the state is
-  // stored in a ref, and updates are triggered with forceUpdate when necessary.
-  const state = useRef(undefined as S);
+  const [state, setState] = useState(initialState);
 
-  const prevDeps = useRef(deps);
-  const isMounted = useRef(false);
+  const [prevDeps, setPrevDeps] = useState(deps);
 
-  // If first render, or if dependencies have changed since last time
-  if (!isMounted.current || !depsAreEqual(prevDeps.current, deps)) {
-    // Update state and deps
-    let nextState: S;
-    if (isFunction(initialState)) {
-      nextState = initialState(state.current);
-    } else {
-      nextState = initialState;
-    }
-    state.current = nextState;
-    prevDeps.current = deps;
-    isMounted.current = true;
+  if (!depsAreEqual(deps, prevDeps)) {
+    setPrevDeps(deps);
+    setState(initialState);
   }
 
-  const [forceUpdate] = useForceUpdate();
-
-  const updateState = useCallback(function updateState(
-    newState: S | ((previousState: S) => S),
-  ): void {
-    let nextState: S;
-    if (isFunction(newState)) {
-      nextState = newState(state.current);
-    } else {
-      nextState = newState;
-    }
-    if (!Object.is(state.current, nextState)) {
-      state.current = nextState;
-      forceUpdate();
-    }
-  }, []); // eslint-disable-line react-hooks/exhaustive-deps
-
-  return [state.current, updateState];
+  return [state, setState];
 }

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
@@ -22,7 +23,9 @@ export type RestrictedContext<T> =
 /**
  * The return type of {@linkcode createSafeContext}
  *
- * @see {@linkcode createSafeContext}
+ * @see
+ * {@linkcode createSafeContext},
+ * {@linkcode RestrictedContext}
  */
 export type SafeContext<DisplayName extends string, T> = {
   [K in `${DisplayName}Context`]: RestrictedContext<T>;
@@ -85,6 +88,9 @@ export type SafeContext<DisplayName extends string, 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>(

package/src/utils.ts

@@ -1,19 +1,11 @@
 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,