@aweebit/react-essentials 0.6.0 → 0.7.0

package/dist/hooks/useEventListener.d.ts

@@ -4,13 +4,21 @@
  * @license MIT
  * @copyright 2020 Julien CARON
  */
+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
+];
 /**
- * Adds `handler` as a listener for the event `eventName` of `element` with the
+ * Adds `handler` as a listener for the event `eventName` of `target` with the
  * provided `options` applied
  *
- * If `element` is `undefined`, `window` is used instead.
+ * If `target` is not provided, `window` is used instead.
  *
- * If `element` is `null`, no event listener is added.
+ * 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
@@ -18,62 +26,49 @@
  *   console.log(window.innerWidth, window.innerHeight);
  * });
  *
- * useEventListener(
- *   'visibilitychange',
- *   () => console.log(document.visibilityState),
- *   document
- * );
+ * useEventListener(document, 'visibilitychange', () => {
+ *   console.log(document.visibilityState);
+ * });
  *
  * const buttonRef = useRef<HTMLButtonElement>(null);
- * useEventListener("click", () => console.log("click"), buttonRef.current);
+ * useEventListener(buttonRef.current, 'click', () => console.log('click'));
  * ```
  *
  * @ignore
  */
-export declare function useEventListener<K extends keyof HTMLElementEventMap, T extends HTMLElement>(eventName: K, handler: (this: NoInfer<T>, event: HTMLElementEventMap[K]) => void, element: T | null, options?: boolean | AddEventListenerOptions): void;
+export declare function useEventListener<K extends keyof WindowEventMap>(eventName: K, handler: (this: Window, event: WindowEventMap[K]) => void, options?: AddEventListenerOptions | boolean): void;
 /**
  * @see {@linkcode useEventListener}
  * @ignore
  */
-export declare function useEventListener<K extends keyof SVGElementEventMap, T extends SVGElement>(eventName: K, handler: (this: NoInfer<T>, event: SVGElementEventMap[K]) => void, element: T | null, options?: boolean | AddEventListenerOptions): void;
+export declare function useEventListener<K extends keyof WindowEventMap>(...args: UseEventListenerOverloadArgs<WindowEventMap, K, Window>): void;
 /**
  * @see {@linkcode useEventListener}
  * @ignore
  */
-export declare function useEventListener<K extends keyof MathMLElementEventMap, T extends MathMLElement>(eventName: K, handler: (this: NoInfer<T>, event: MathMLElementEventMap[K]) => void, element: T | null, options?: boolean | AddEventListenerOptions): void;
+export declare function useEventListener<K extends keyof DocumentEventMap>(...args: UseEventListenerOverloadArgs<DocumentEventMap, K, Document>): void;
 /**
  * @see {@linkcode useEventListener}
  * @ignore
  */
-export declare function useEventListener<K extends keyof DocumentEventMap>(eventName: K, handler: (this: Document, event: DocumentEventMap[K]) => void, element: Document, options?: boolean | AddEventListenerOptions): void;
+export declare function useEventListener<K extends keyof HTMLElementEventMap, T extends HTMLElement>(...args: UseEventListenerOverloadArgs<HTMLElementEventMap, K, T>): void;
 /**
  * @see {@linkcode useEventListener}
  * @ignore
  */
-export declare function useEventListener<K extends keyof WindowEventMap>(eventName: K, handler: (this: Window, event: WindowEventMap[K]) => void, element?: Window, options?: boolean | AddEventListenerOptions): void;
+export declare function useEventListener<K extends keyof SVGElementEventMap, T extends SVGElement>(...args: UseEventListenerOverloadArgs<SVGElementEventMap, K, T>): void;
 /**
- * Adds `handler` as a listener for the event `eventName` of `element` with the
- * provided `options` applied
- *
- * If `element` is `undefined`, `window` is used instead.
- *
- * If `element` is `null`, no event listener is added.
- *
- * @example
- * ```tsx
- * useEventListener('resize', () => {
- *   console.log(window.innerWidth, window.innerHeight);
- * });
- *
- * useEventListener(
- *   'visibilitychange',
- *   () => console.log(document.visibilityState),
- *   document
- * );
- *
- * const buttonRef = useRef<HTMLButtonElement>(null);
- * useEventListener("click", () => console.log("click"), buttonRef.current);
- * ```
+ * @see {@linkcode useEventListener}
+ * @ignore
+ */
+export declare function useEventListener<K extends keyof MathMLElementEventMap, T extends MathMLElement>(...args: UseEventListenerOverloadArgs<MathMLElementEventMap, K, T>): void;
+/**
+ * @see {@linkcode useEventListener}
+ */
+export declare function useEventListener<K extends keyof WindowEventMap>(eventName: K, handler: (this: Window, event: WindowEventMap[K]) => void, options?: AddEventListenerOptions | boolean): void;
+/**
+ * @see {@linkcode useEventListener}
  */
-export declare function useEventListener<T extends EventTarget>(eventName: string, handler: (this: NoInfer<T>, event: Event) => void, element?: T | null, options?: boolean | AddEventListenerOptions): void;
+export declare function useEventListener<T extends EventTarget>(target: T | null, eventName: string, handler: (this: NoInfer<T>, event: Event) => void, options?: AddEventListenerOptions | boolean): void;
+export {};
 //# sourceMappingURL=useEventListener.d.ts.map

package/dist/hooks/useEventListener.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useEventListener.d.ts","sourceRoot":"","sources":["../../src/hooks/useEventListener.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,gBAAgB,CAC9B,CAAC,SAAS,MAAM,mBAAmB,EACnC,CAAC,SAAS,WAAW,EAErB,SAAS,EAAE,CAAC,EACZ,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,mBAAmB,CAAC,CAAC,CAAC,KAAK,IAAI,EAClE,OAAO,EAAE,CAAC,GAAG,IAAI,EACjB,OAAO,CAAC,EAAE,OAAO,GAAG,uBAAuB,GAC1C,IAAI,CAAC;AAER;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,CAAC,SAAS,MAAM,kBAAkB,EAClC,CAAC,SAAS,UAAU,EAEpB,SAAS,EAAE,CAAC,EACZ,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,kBAAkB,CAAC,CAAC,CAAC,KAAK,IAAI,EACjE,OAAO,EAAE,CAAC,GAAG,IAAI,EACjB,OAAO,CAAC,EAAE,OAAO,GAAG,uBAAuB,GAC1C,IAAI,CAAC;AAER;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,CAAC,SAAS,MAAM,qBAAqB,EACrC,CAAC,SAAS,aAAa,EAEvB,SAAS,EAAE,CAAC,EACZ,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,qBAAqB,CAAC,CAAC,CAAC,KAAK,IAAI,EACpE,OAAO,EAAE,CAAC,GAAG,IAAI,EACjB,OAAO,CAAC,EAAE,OAAO,GAAG,uBAAuB,GAC1C,IAAI,CAAC;AAER;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,gBAAgB,EAC/D,SAAS,EAAE,CAAC,EACZ,OAAO,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,gBAAgB,CAAC,CAAC,CAAC,KAAK,IAAI,EAC7D,OAAO,EAAE,QAAQ,EACjB,OAAO,CAAC,EAAE,OAAO,GAAG,uBAAuB,GAC1C,IAAI,CAAC;AAER;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,cAAc,EAC7D,SAAS,EAAE,CAAC,EACZ,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,KAAK,IAAI,EACzD,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,OAAO,GAAG,uBAAuB,GAC1C,IAAI,CAAC;AAER;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,WAAW,EACpD,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,EACjD,OAAO,CAAC,EAAE,CAAC,GAAG,IAAI,EAClB,OAAO,CAAC,EAAE,OAAO,GAAG,uBAAuB,GAC1C,IAAI,CAAC"}
+{"version":3,"file":"useEventListener.d.ts","sourceRoot":"","sources":["../../src/hooks/useEventListener.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,KAAK,4BAA4B,CAC/B,QAAQ,EACR,CAAC,SAAS,MAAM,QAAQ,EACxB,CAAC,SAAS,WAAW,IACnB;IACF,MAAM,EAAE,CAAC,GAAG,IAAI;IAChB,SAAS,EAAE,CAAC;IACZ,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,IAAI;IACvD,OAAO,CAAC,EAAE,uBAAuB,GAAG,OAAO;CAC5C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,cAAc,EAC7D,SAAS,EAAE,CAAC,EACZ,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,KAAK,IAAI,EACzD,OAAO,CAAC,EAAE,uBAAuB,GAAG,OAAO,GAC1C,IAAI,CAAC;AAER;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,cAAc,EAC7D,GAAG,IAAI,EAAE,4BAA4B,CAAC,cAAc,EAAE,CAAC,EAAE,MAAM,CAAC,GAC/D,IAAI,CAAC;AAER;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,gBAAgB,EAC/D,GAAG,IAAI,EAAE,4BAA4B,CAAC,gBAAgB,EAAE,CAAC,EAAE,QAAQ,CAAC,GACnE,IAAI,CAAC;AAER;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,CAAC,SAAS,MAAM,mBAAmB,EACnC,CAAC,SAAS,WAAW,EACrB,GAAG,IAAI,EAAE,4BAA4B,CAAC,mBAAmB,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;AAE1E;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,CAAC,SAAS,MAAM,kBAAkB,EAClC,CAAC,SAAS,UAAU,EACpB,GAAG,IAAI,EAAE,4BAA4B,CAAC,kBAAkB,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;AAEzE;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,CAAC,SAAS,MAAM,qBAAqB,EACrC,CAAC,SAAS,aAAa,EACvB,GAAG,IAAI,EAAE,4BAA4B,CAAC,qBAAqB,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;AAE5E;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,cAAc,EAC7D,SAAS,EAAE,CAAC,EACZ,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,KAAK,IAAI,EACzD,OAAO,CAAC,EAAE,uBAAuB,GAAG,OAAO,GAC1C,IAAI,CAAC;AAER;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,WAAW,EACpD,MAAM,EAAE,CAAC,GAAG,IAAI,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,EACjD,OAAO,CAAC,EAAE,uBAAuB,GAAG,OAAO,GAC1C,IAAI,CAAC"}

package/dist/hooks/useEventListener.js

@@ -5,7 +5,42 @@
  * @copyright 2020 Julien CARON
  */
 import { useEffect, useMemo, useRef } from 'react';
-export function useEventListener(eventName, handler, element, options) {
+/**
+ * Adds `handler` as a listener for the event `eventName` of `target` with the
+ * provided `options` applied
+ *
+ * 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'));
+ * ```
+ */
+export function useEventListener(...args) {
+    let eventName;
+    let handler;
+    let target;
+    let options;
+    if (typeof args[0] === 'string') {
+        [eventName, handler, options] = args;
+    }
+    else {
+        [target, eventName, handler, options] =
+            args;
+    }
     const handlerRef = useRef(handler);
     handlerRef.current = handler;
     const { capture = false, once = false, passive, signal, } = typeof options === 'boolean' ? { capture: options } : (options ?? {});
@@ -13,21 +48,18 @@ export function useEventListener(eventName, handler, element, options) {
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [capture, once, passive, signal]);
     useEffect(() => {
-        if (element === null) {
+        if (target === null) {
             // No element has been attached to the ref yet
             return;
         }
-        // Define the listening target
-        const targetElement = element ?? window;
-        // Create event listener that calls handler function stored in ref
+        const definedTarget = target ?? window;
         const listener = function (event) {
             handlerRef.current.call(this, event);
         };
-        targetElement.addEventListener(eventName, listener, memoizedOptions);
-        // Remove event listener on cleanup
+        definedTarget.addEventListener(eventName, listener, memoizedOptions);
         return () => {
-            targetElement.removeEventListener(eventName, listener, memoizedOptions);
+            definedTarget.removeEventListener(eventName, listener, memoizedOptions);
         };
-    }, [eventName, element, memoizedOptions]);
+    }, [eventName, target, memoizedOptions]);
 }
 //# sourceMappingURL=useEventListener.js.map

package/dist/hooks/useEventListener.js.map

@@ -1 +1 @@
-{"version":3,"file":"useEventListener.js","sourceRoot":"","sources":["../../src/hooks/useEventListener.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAuHnD,MAAM,UAAU,gBAAgB,CAC9B,SAAiB,EACjB,OAAkD,EAClD,OAA4B,EAC5B,OAA2C;IAE3C,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IACnC,UAAU,CAAC,OAAO,GAAG,OAAO,CAAC;IAE7B,MAAM,EACJ,OAAO,GAAG,KAAK,EACf,IAAI,GAAG,KAAK,EACZ,OAAO,EACP,MAAM,GACP,GAAG,OAAO,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;IAE1E,MAAM,eAAe,GAAG,OAAO,CAC7B,GAAG,EAAE,CAAC,OAAO;IACb,uDAAuD;IACvD,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,CACjC,CAAC;IAEF,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACrB,8CAA8C;YAC9C,OAAO;QACT,CAAC;QAED,8BAA8B;QAC9B,MAAM,aAAa,GAAG,OAAO,IAAI,MAAM,CAAC;QAExC,kEAAkE;QAClE,MAAM,QAAQ,GAAmB,UAAU,KAAK;YAC9C,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACvC,CAAC,CAAC;QAEF,aAAa,CAAC,gBAAgB,CAAC,SAAS,EAAE,QAAQ,EAAE,eAAe,CAAC,CAAC;QAErE,mCAAmC;QACnC,OAAO,GAAG,EAAE;YACV,aAAa,CAAC,mBAAmB,CAAC,SAAS,EAAE,QAAQ,EAAE,eAAe,CAAC,CAAC;QAC1E,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC;AAC5C,CAAC"}
+{"version":3,"file":"useEventListener.js","sourceRoot":"","sources":["../../src/hooks/useEventListener.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AA2GnD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,gBAAgB,CAC9B,GAAG,IAAwE;IAE3E,IAAI,SAAiB,CAAC;IACtB,IAAI,OAAkD,CAAC;IACvD,IAAI,MAAsC,CAAC;IAC3C,IAAI,OAAsD,CAAC;IAE3D,IAAI,OAAO,IAAI,CAAC,CAAC,CAAC,KAAK,QAAQ,EAAE,CAAC;QAChC,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,CAAC,GAAG,IAAyC,CAAC;IAC5E,CAAC;SAAM,CAAC;QACN,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,CAAC;YACnC,IAAsC,CAAC;IAC3C,CAAC;IAED,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IACnC,UAAU,CAAC,OAAO,GAAG,OAAO,CAAC;IAE7B,MAAM,EACJ,OAAO,GAAG,KAAK,EACf,IAAI,GAAG,KAAK,EACZ,OAAO,EACP,MAAM,GACP,GAAG,OAAO,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;IAE1E,MAAM,eAAe,GAAG,OAAO,CAC7B,GAAG,EAAE,CAAC,OAAO;IACb,uDAAuD;IACvD,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,CACjC,CAAC;IAEF,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;YACpB,8CAA8C;YAC9C,OAAO;QACT,CAAC;QAED,MAAM,aAAa,GAAG,MAAM,IAAI,MAAM,CAAC;QAEvC,MAAM,QAAQ,GAAmB,UAAU,KAAK;YAC9C,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACvC,CAAC,CAAC;QAEF,aAAa,CAAC,gBAAgB,CAAC,SAAS,EAAE,QAAQ,EAAE,eAAe,CAAC,CAAC;QAErE,OAAO,GAAG,EAAE;YACV,aAAa,CAAC,mBAAmB,CAAC,SAAS,EAAE,QAAQ,EAAE,eAAe,CAAC,CAAC;QAC1E,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC;AAC3C,CAAC"}

package/dist/hooks/useForceUpdate.d.ts

@@ -4,6 +4,55 @@
  * 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],
+ * );
+ * ```
+ *
  * @param callback An optional callback function to call during renders that
  * were triggered with `forceUpdate()`
  *

package/dist/hooks/useForceUpdate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useForceUpdate.d.ts","sourceRoot":"","sources":["../../src/hooks/useForceUpdate.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,cAAc,CAAC,QAAQ,CAAC,EAAE,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,EAAE,MAAM,CAAC,CAU1E"}
+{"version":3,"file":"useForceUpdate.d.ts","sourceRoot":"","sources":["../../src/hooks/useForceUpdate.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,CAAC,EAAE,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,EAAE,MAAM,CAAC,CAU1E"}

package/dist/hooks/useForceUpdate.js

@@ -6,6 +6,55 @@ import { useReducer, useRef } from 'react';
  * 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],
+ * );
+ * ```
+ *
  * @param callback An optional callback function to call during renders that
  * were triggered with `forceUpdate()`
  *
@@ -27,12 +76,12 @@ import { useReducer, useRef } from 'react';
 export function useForceUpdate(callback) {
     // It is very unlikely that the number of updates will exceed
     // Number.MAX_SAFE_INTEGER, but not impossible. That is why we use bigints.
-    const [counter, forceUpdate] = useReducer((prev) => prev + 1n, 0n);
-    const counterRef = useRef(counter);
-    if (counter !== counterRef.current) {
-        counterRef.current = counter;
+    const [updateCount, forceUpdate] = useReducer((prev) => prev + 1n, 0n);
+    const updateCountRef = useRef(updateCount);
+    if (updateCount !== updateCountRef.current) {
+        updateCountRef.current = updateCount;
         callback?.();
     }
-    return [forceUpdate, counter];
+    return [forceUpdate, updateCount];
 }
 //# sourceMappingURL=useForceUpdate.js.map

package/dist/hooks/useForceUpdate.js.map

@@ -1 +1 @@
-{"version":3,"file":"useForceUpdate.js","sourceRoot":"","sources":["../../src/hooks/useForceUpdate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAK3C,mBAAmB;AAEnB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,cAAc,CAAC,QAAqB;IAClD,6DAA6D;IAC7D,2EAA2E;IAC3E,MAAM,CAAC,OAAO,EAAE,WAAW,CAAC,GAAG,UAAU,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,EAAE,EAAE,EAAE,CAAC,CAAC;IACnE,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IACnC,IAAI,OAAO,KAAK,UAAU,CAAC,OAAO,EAAE,CAAC;QACnC,UAAU,CAAC,OAAO,GAAG,OAAO,CAAC;QAC7B,QAAQ,EAAE,EAAE,CAAC;IACf,CAAC;IACD,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;AAChC,CAAC"}
+{"version":3,"file":"useForceUpdate.js","sourceRoot":"","sources":["../../src/hooks/useForceUpdate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAK3C,mBAAmB;AAEnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AACH,MAAM,UAAU,cAAc,CAAC,QAAqB;IAClD,6DAA6D;IAC7D,2EAA2E;IAC3E,MAAM,CAAC,WAAW,EAAE,WAAW,CAAC,GAAG,UAAU,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,EAAE,EAAE,EAAE,CAAC,CAAC;IACvE,MAAM,cAAc,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;IAC3C,IAAI,WAAW,KAAK,cAAc,CAAC,OAAO,EAAE,CAAC;QAC3C,cAAc,CAAC,OAAO,GAAG,WAAW,CAAC;QACrC,QAAQ,EAAE,EAAE,CAAC;IACf,CAAC;IACD,OAAO,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;AACpC,CAAC"}

package/dist/hooks/useReducerWithDeps.d.ts

@@ -7,6 +7,9 @@ export type ActionDispatch<ActionArg extends AnyActionArg> = (...args: ActionArg
  * `useReducer` hook with an additional dependency array `deps` that resets the
  * state to `initialState` when dependencies change
  *
+ * For motivation and examples, see
+ * https://github.com/facebook/react/issues/33041.
+ *
  * ### On linter support
  *
  * The `react-hooks/exhaustive-deps` ESLint rule doesn't support hooks where
@@ -15,7 +18,7 @@ export type ActionDispatch<ActionArg extends AnyActionArg> = (...args: ActionArg
  * possible, we don't want to artificially change the parameter's position.
  * Therefore, there will be no warnings about missing dependencies.
  * Because of that, additional caution is advised!
- * Be sure to check no dependencies are missing from the `deps` array.
+ * Be sure to check that no dependencies are missing from the `deps` array.
  *
  * Related issue: {@link https://github.com/facebook/react/issues/25443}.
  *

package/dist/hooks/useReducerWithDeps.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useReducerWithDeps.d.ts","sourceRoot":"","sources":["../../src/hooks/useReducerWithDeps.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,cAAc,EAAuB,MAAM,OAAO,CAAC;AAOjE,cAAc;AAEd,MAAM,MAAM,YAAY,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;AAEtC,cAAc;AACd,MAAM,MAAM,cAAc,CAAC,SAAS,SAAS,YAAY,IAAI,CAC3D,GAAG,IAAI,EAAE,SAAS,KACf,IAAI,CAAC;AAEV;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,CAAC,SAAS,YAAY,EAC1D,OAAO,EAAE,CAAC,SAAS,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC,KAAK,CAAC,EACxC,YAAY,EAAE,CAAC,GAAG,CAAC,CAAC,aAAa,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAC5C,IAAI,EAAE,cAAc,GACnB,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC,CAYxB"}
+{"version":3,"file":"useReducerWithDeps.d.ts","sourceRoot":"","sources":["../../src/hooks/useReducerWithDeps.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,cAAc,EAAuB,MAAM,OAAO,CAAC;AAOjE,cAAc;AAEd,MAAM,MAAM,YAAY,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;AAEtC,cAAc;AACd,MAAM,MAAM,cAAc,CAAC,SAAS,SAAS,YAAY,IAAI,CAC3D,GAAG,IAAI,EAAE,SAAS,KACf,IAAI,CAAC;AAEV;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,CAAC,SAAS,YAAY,EAC1D,OAAO,EAAE,CAAC,SAAS,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC,KAAK,CAAC,EACxC,YAAY,EAAE,CAAC,GAAG,CAAC,CAAC,aAAa,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAC5C,IAAI,EAAE,cAAc,GACnB,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC,CAYxB"}

package/dist/hooks/useReducerWithDeps.js

@@ -4,6 +4,9 @@ import { useStateWithDeps } from './useStateWithDeps.js';
  * `useReducer` hook with an additional dependency array `deps` that resets the
  * state to `initialState` when dependencies change
  *
+ * For motivation and examples, see
+ * https://github.com/facebook/react/issues/33041.
+ *
  * ### On linter support
  *
  * The `react-hooks/exhaustive-deps` ESLint rule doesn't support hooks where
@@ -12,7 +15,7 @@ import { useStateWithDeps } from './useStateWithDeps.js';
  * possible, we don't want to artificially change the parameter's position.
  * Therefore, there will be no warnings about missing dependencies.
  * Because of that, additional caution is advised!
- * Be sure to check no dependencies are missing from the `deps` array.
+ * Be sure to check that no dependencies are missing from the `deps` array.
  *
  * Related issue: {@link https://github.com/facebook/react/issues/25443}.
  *

package/dist/hooks/useReducerWithDeps.js.map

@@ -1 +1 @@
-{"version":3,"file":"useReducerWithDeps.js","sourceRoot":"","sources":["../../src/hooks/useReducerWithDeps.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,WAAW,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAezD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAAwC,EACxC,YAA4C,EAC5C,IAAoB;IAEpB,uDAAuD;IACvD,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,gBAAgB,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;IAE/D,8CAA8C;IAC9C,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IAEnC,MAAM,QAAQ,GAAG,WAAW,CAAC,SAAS,QAAQ,CAAC,GAAG,IAAO;QACvD,QAAQ,CAAC,CAAC,aAAa,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC;IAC1E,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,kDAAkD;IAE1D,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;AAC3B,CAAC"}
+{"version":3,"file":"useReducerWithDeps.js","sourceRoot":"","sources":["../../src/hooks/useReducerWithDeps.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,WAAW,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAezD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAAwC,EACxC,YAA4C,EAC5C,IAAoB;IAEpB,uDAAuD;IACvD,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,gBAAgB,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;IAE/D,8CAA8C;IAC9C,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IAEnC,MAAM,QAAQ,GAAG,WAAW,CAAC,SAAS,QAAQ,CAAC,GAAG,IAAO;QACvD,QAAQ,CAAC,CAAC,aAAa,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC;IAC1E,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,kDAAkD;IAE1D,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;AAC3B,CAAC"}

package/dist/hooks/useStateWithDeps.d.ts

@@ -9,6 +9,41 @@ import { type DependencyList, type Dispatch, type SetStateAction } from 'react';
  * `useState` hook with an additional dependency array `deps` that resets the
  * state to `initialState` when dependencies change
  *
+ * For motivation and more examples, see
+ * https://github.com/facebook/react/issues/33041.
+ *
+ * @example
+ * ```tsx
+ * type Activity = 'breakfast' | 'exercise' | 'swim' | 'board games' | 'dinner';
+ *
+ * const timeOfDayOptions = ['morning', 'afternoon', 'evening'] as const;
+ * type TimeOfDay = (typeof timeOfDayOptions)[number];
+ *
+ * const activityOptionsByTimeOfDay: {
+ *   [K in TimeOfDay]: [Activity, ...Activity[]];
+ * } = {
+ *   morning: ['breakfast', 'exercise', 'swim'],
+ *   afternoon: ['exercise', 'swim', 'board games'],
+ *   evening: ['board games', 'dinner'],
+ * };
+ *
+ * export function Example() {
+ *   const [timeOfDay, setTimeOfDay] = useState<TimeOfDay>('morning');
+ *
+ *   const activityOptions = activityOptionsByTimeOfDay[timeOfDay];
+ *   const [activity, setActivity] = useStateWithDeps<Activity>(
+ *     (prev) => {
+ *       // Make sure activity is always valid for the current timeOfDay value,
+ *       // but also don't reset it unless necessary:
+ *       return prev && activityOptions.includes(prev) ? prev : activityOptions[0];
+ *     },
+ *     [activityOptions],
+ *   );
+ *
+ *   return '...';
+ * }
+ * ```
+ *
  * @param initialState The value to which the state is set when the component is
  * mounted or dependencies change
  *

package/dist/hooks/useStateWithDeps.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useStateWithDeps.d.ts","sourceRoot":"","sources":["../../src/hooks/useStateWithDeps.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,cAAc,EACpB,MAAM,OAAO,CAAC;AAIf;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,YAAY,EAAE,CAAC,GAAG,CAAC,CAAC,aAAa,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAC5C,IAAI,EAAE,cAAc,GACnB,CAAC,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CA4ClC"}
+{"version":3,"file":"useStateWithDeps.d.ts","sourceRoot":"","sources":["../../src/hooks/useStateWithDeps.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,cAAc,EACpB,MAAM,OAAO,CAAC;AAIf;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,YAAY,EAAE,CAAC,GAAG,CAAC,CAAC,aAAa,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAC5C,IAAI,EAAE,cAAc,GACnB,CAAC,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CA0ClC"}

package/dist/hooks/useStateWithDeps.js

@@ -11,6 +11,41 @@ import { useForceUpdate } from './useForceUpdate.js';
  * `useState` hook with an additional dependency array `deps` that resets the
  * state to `initialState` when dependencies change
  *
+ * For motivation and more examples, see
+ * https://github.com/facebook/react/issues/33041.
+ *
+ * @example
+ * ```tsx
+ * type Activity = 'breakfast' | 'exercise' | 'swim' | 'board games' | 'dinner';
+ *
+ * const timeOfDayOptions = ['morning', 'afternoon', 'evening'] as const;
+ * type TimeOfDay = (typeof timeOfDayOptions)[number];
+ *
+ * const activityOptionsByTimeOfDay: {
+ *   [K in TimeOfDay]: [Activity, ...Activity[]];
+ * } = {
+ *   morning: ['breakfast', 'exercise', 'swim'],
+ *   afternoon: ['exercise', 'swim', 'board games'],
+ *   evening: ['board games', 'dinner'],
+ * };
+ *
+ * export function Example() {
+ *   const [timeOfDay, setTimeOfDay] = useState<TimeOfDay>('morning');
+ *
+ *   const activityOptions = activityOptionsByTimeOfDay[timeOfDay];
+ *   const [activity, setActivity] = useStateWithDeps<Activity>(
+ *     (prev) => {
+ *       // Make sure activity is always valid for the current timeOfDay value,
+ *       // but also don't reset it unless necessary:
+ *       return prev && activityOptions.includes(prev) ? prev : activityOptions[0];
+ *     },
+ *     [activityOptions],
+ *   );
+ *
+ *   return '...';
+ * }
+ * ```
+ *
  * @param initialState The value to which the state is set when the component is
  * mounted or dependencies change
  *
@@ -21,12 +56,10 @@ import { useForceUpdate } from './useForceUpdate.js';
  * @param deps Dependencies that reset the state to `initialState`
  */
 export function useStateWithDeps(initialState, deps) {
-    // 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 an
-    // update is triggered via forceUpdate below when necessary
+    // 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);
     const prevDeps = useRef(deps);
     const isMounted = useRef(false);

package/dist/hooks/useStateWithDeps.js.map

@@ -1 +1 @@
-{"version":3,"file":"useStateWithDeps.js","sourceRoot":"","sources":["../../src/hooks/useStateWithDeps.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,WAAW,EACX,MAAM,GAIP,MAAM,OAAO,CAAC;AACf,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,gBAAgB,CAC9B,YAA4C,EAC5C,IAAoB;IAEpB,kDAAkD;IAClD,gDAAgD;IAChD,qDAAqD;IACrD,uDAAuD;IACvD,kDAAkD;IAClD,2DAA2D;IAC3D,MAAM,KAAK,GAAG,MAAM,CAAC,SAAc,CAAC,CAAC;IAErC,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAC9B,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAEhC,mEAAmE;IACnE,IAAI,CAAC,SAAS,CAAC,OAAO,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,CAAC;QAChE,wBAAwB;QACxB,IAAI,SAAY,CAAC;QACjB,IAAI,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;YAC7B,SAAS,GAAG,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC1C,CAAC;aAAM,CAAC;YACN,SAAS,GAAG,YAAY,CAAC;QAC3B,CAAC;QACD,KAAK,CAAC,OAAO,GAAG,SAAS,CAAC;QAC1B,QAAQ,CAAC,OAAO,GAAG,IAAI,CAAC;QACxB,SAAS,CAAC,OAAO,GAAG,IAAI,CAAC;IAC3B,CAAC;IAED,MAAM,CAAC,WAAW,CAAC,GAAG,cAAc,EAAE,CAAC;IAEvC,MAAM,WAAW,GAAG,WAAW,CAAC,SAAS,WAAW,CAClD,QAAuC;QAEvC,IAAI,SAAY,CAAC;QACjB,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YACzB,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACtC,CAAC;aAAM,CAAC;YACN,SAAS,GAAG,QAAQ,CAAC;QACvB,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,CAAC;YACzC,KAAK,CAAC,OAAO,GAAG,SAAS,CAAC;YAC1B,WAAW,EAAE,CAAC;QAChB,CAAC;IACH,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,kDAAkD;IAE1D,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;AACtC,CAAC"}
+{"version":3,"file":"useStateWithDeps.js","sourceRoot":"","sources":["../../src/hooks/useStateWithDeps.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,WAAW,EACX,MAAM,GAIP,MAAM,OAAO,CAAC;AACf,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,MAAM,UAAU,gBAAgB,CAC9B,YAA4C,EAC5C,IAAoB;IAEpB,6EAA6E;IAC7E,6EAA6E;IAC7E,2EAA2E;IAC3E,8EAA8E;IAC9E,MAAM,KAAK,GAAG,MAAM,CAAC,SAAc,CAAC,CAAC;IAErC,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAC9B,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAEhC,mEAAmE;IACnE,IAAI,CAAC,SAAS,CAAC,OAAO,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,CAAC;QAChE,wBAAwB;QACxB,IAAI,SAAY,CAAC;QACjB,IAAI,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;YAC7B,SAAS,GAAG,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC1C,CAAC;aAAM,CAAC;YACN,SAAS,GAAG,YAAY,CAAC;QAC3B,CAAC;QACD,KAAK,CAAC,OAAO,GAAG,SAAS,CAAC;QAC1B,QAAQ,CAAC,OAAO,GAAG,IAAI,CAAC;QACxB,SAAS,CAAC,OAAO,GAAG,IAAI,CAAC;IAC3B,CAAC;IAED,MAAM,CAAC,WAAW,CAAC,GAAG,cAAc,EAAE,CAAC;IAEvC,MAAM,WAAW,GAAG,WAAW,CAAC,SAAS,WAAW,CAClD,QAAuC;QAEvC,IAAI,SAAY,CAAC;QACjB,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YACzB,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACtC,CAAC;aAAM,CAAC;YACN,SAAS,GAAG,QAAQ,CAAC;QACvB,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,CAAC;YACzC,KAAK,CAAC,OAAO,GAAG,SAAS,CAAC;YAC1B,WAAW,EAAE,CAAC;QAChB,CAAC;IACH,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,kDAAkD;IAE1D,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;AACtC,CAAC"}

package/dist/misc/createSafeContext.d.ts

@@ -16,6 +16,8 @@ export type RestrictedContext<T> = Context<T> extends Provider<T> ? {
     displayName: string;
 };
 /**
+ * The return type of {@linkcode createSafeContext}
+ *
  * @see {@linkcode createSafeContext}
  */
 export type SafeContext<DisplayName extends string, T> = {
@@ -28,24 +30,55 @@ 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
  */
 export declare function createSafeContext<T = never>(): <DisplayName extends string>(displayName: [T] extends [never] ? never : ArgumentFallback<DisplayName, never, string>) => SafeContext<DisplayName, T>;

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;;;;;;;GAOG;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;;GAEG;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;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;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,EAAE,KAAK,QAAQ,EAA6B,MAAM,OAAO,CAAC;AAC/E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAIpD;;;;;;;GAOG;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;;;;GAIG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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,WAAW,CAAC,WAAW,EAAE,CAAC,CAAC,CAsB/B"}