@vertigis/react-ui 11.1.0 → 11.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@vertigis/react-ui",
-    "version": "11.1.0",
+    "version": "11.2.0",
     "description": "Utilities and React components used in VertiGIS applications.",
     "keywords": [
         "vertigis",

package/utils/debounce.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Debounces a function, i.e. creates a wrapper that only invokes the original
+ * once a certain amount of time has elapsed without being invoked.
+ *
+ * @param func The original function.
+ * @param wait The amount of time to wait for inactivity (in milliseconds).
+ * @param immediate If true, trigger the function on the leading edge, instead
+ *   of the trailing.
+ */
+export declare function debounce<T extends unknown[]>(func: (...args: [...T]) => void, wait: number, immediate?: boolean): (...args: [...T]) => void;
+/**
+ * Same as `debounce()`, but optimized for animation and rendering.
+ *
+ * @param func The function to debounce.
+ */
+export declare function debounceAnimation<T extends unknown[]>(func: (...args: [...T]) => void): (...args: [...T]) => void;

package/utils/debounce.js

@@ -0,0 +1,39 @@
+/**
+ * Debounces a function, i.e. creates a wrapper that only invokes the original
+ * once a certain amount of time has elapsed without being invoked.
+ *
+ * @param func The original function.
+ * @param wait The amount of time to wait for inactivity (in milliseconds).
+ * @param immediate If true, trigger the function on the leading edge, instead
+ *   of the trailing.
+ */
+export function debounce(func, wait, immediate) {
+    // Taken from https://davidwalsh.name/function-debounce, originally from Underscore.js
+    let timeout;
+    return (...args) => {
+        const later = () => {
+            timeout = undefined;
+            if (!immediate) {
+                func(...args);
+            }
+        };
+        const callNow = immediate && !timeout;
+        clearTimeout(timeout);
+        timeout = window.setTimeout(later, wait);
+        if (callNow) {
+            func(...args);
+        }
+    };
+}
+/**
+ * Same as `debounce()`, but optimized for animation and rendering.
+ *
+ * @param func The function to debounce.
+ */
+export function debounceAnimation(func) {
+    let token;
+    return (...args) => {
+        cancelAnimationFrame(token);
+        token = requestAnimationFrame(() => func(...args));
+    };
+}

package/utils/react.d.ts

@@ -13,3 +13,22 @@ export declare function useId(idProp?: string): string;
  * supports forwarding a ref from its parent component.
  */
 export declare function mergeRefs<T>(...refs: (RefCallback<T> | MutableRefObject<T | null> | null)[]): Ref<T>;
+/**
+ * Returns the previous value of updated props or state.
+ *
+ * @param value The original value of the property.
+ */
+export declare function usePrevious<T = unknown>(value: T | undefined): T | undefined;
+/**
+ * A simple, unoptimized implementation of useResizeObserver.
+ *
+ * @param target The node to observe.
+ * @param callback Called when a change is observed.
+ */
+export declare function useResizeObserver<T extends HTMLElement = HTMLElement>(target: T, callback: (entry: ResizeObserverEntry) => void): void;
+/**
+ * Gets the dimensions of an element.
+ *
+ * @param target A ref to the target element.
+ */
+export declare function useContentRect<T extends HTMLElement = HTMLElement>(target: React.RefObject<T | undefined> | React.MutableRefObject<T | undefined> | T): DOMRectReadOnly;

package/utils/react.js

@@ -1,4 +1,4 @@
-import { useState } from "react";
+import { useCallback, useLayoutEffect, useEffect, useRef, useState } from "react";
 /**
  * Generate a random 10 digit id.
  *
@@ -40,3 +40,59 @@ export function mergeRefs(...refs) {
         });
     };
 }
+/**
+ * Returns the previous value of updated props or state.
+ *
+ * @param value The original value of the property.
+ */
+export function usePrevious(value) {
+    const ref = useRef();
+    useEffect(() => {
+        ref.current = value;
+    }, [value]);
+    return ref.current;
+}
+/**
+ * A simple, unoptimized implementation of useResizeObserver.
+ *
+ * @param target The node to observe.
+ * @param callback Called when a change is observed.
+ */
+export function useResizeObserver(target, callback) {
+    const observer = useRef();
+    const disconnect = useCallback(() => observer.current?.disconnect(), []);
+    const observe = useCallback(() => {
+        if (window.ResizeObserver) {
+            observer.current = new ResizeObserver(([entry]) => callback(entry));
+            if (target) {
+                observer.current.observe(target);
+            }
+        }
+    }, [callback, target]);
+    useLayoutEffect(() => {
+        observe();
+        return () => disconnect();
+    }, [disconnect, observe]);
+}
+/**
+ * Gets the dimensions of an element.
+ *
+ * @param target A ref to the target element.
+ */
+export function useContentRect(target) {
+    const [rect, setRect] = useState();
+    const [element, setElement] = useState();
+    useLayoutEffect(() => {
+        const el = Object.prototype.hasOwnProperty.call(target, "current")
+            ? target.current
+            : target;
+        setRect(el?.getBoundingClientRect());
+        setElement(el);
+    }, [target]);
+    useResizeObserver(element, entry => {
+        if (entry.contentRect.height !== rect?.height || entry.contentRect.width !== rect?.width) {
+            setRect(entry.contentRect);
+        }
+    });
+    return rect ?? {};
+}

package/utils/throttle.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Throttles a function so it can only be fired once per given period of
+ * milliseconds. If the function is called during the throttling period, the
+ * last instance of the function being called will be run once the throttling
+ * period ends. The callback is always invoked asynchronously.
+ *
+ * @param func The function to be throttled.
+ * @param msBetweenRequests The minimum time between requests.
+ */
+export declare function throttle<T extends unknown[]>(func: (...args: [...T]) => void | Promise<void>, msBetweenRequests: number): (...args: [...T]) => void | Promise<void>;
+/**
+ * Same as `throttle()`, but optimized for animation and rendering.
+ *
+ * @param func The function to throttle.
+ */
+export declare function throttleAnimation<T extends unknown[]>(func: (...args: [...T]) => void | Promise<void>): (...args: [...T]) => void | Promise<void>;

package/utils/throttle.js

@@ -0,0 +1,38 @@
+/**
+ * Throttles a function so it can only be fired once per given period of
+ * milliseconds. If the function is called during the throttling period, the
+ * last instance of the function being called will be run once the throttling
+ * period ends. The callback is always invoked asynchronously.
+ *
+ * @param func The function to be throttled.
+ * @param msBetweenRequests The minimum time between requests.
+ */
+export function throttle(func, msBetweenRequests) {
+    let isScheduled = false;
+    return (...args) => {
+        if (!isScheduled) {
+            window.setTimeout(() => {
+                isScheduled = false;
+                void func(...args);
+            }, msBetweenRequests);
+            isScheduled = true;
+        }
+    };
+}
+/**
+ * Same as `throttle()`, but optimized for animation and rendering.
+ *
+ * @param func The function to throttle.
+ */
+export function throttleAnimation(func) {
+    let isScheduled = false;
+    return (...args) => {
+        if (!isScheduled) {
+            requestAnimationFrame(() => {
+                isScheduled = false;
+                void func(...args);
+            });
+            isScheduled = true;
+        }
+    };
+}