@versini/ui-hooks 5.3.2 → 6.0.1

package/dist/useResizeObserver/useResizeObserver.js

@@ -0,0 +1,94 @@
+/*!
+  @versini/ui-hooks v6.0.1
+  © 2025 gizmette.com
+*/
+try {
+  if (!window.__VERSINI_UI_HOOKS__) {
+    window.__VERSINI_UI_HOOKS__ = {
+      version: "6.0.1",
+      buildTime: "12/24/2025 09:19 AM EST",
+      homepage: "https://www.npmjs.com/package/@versini/ui-hooks",
+      license: "MIT",
+    };
+  }
+} catch (error) {
+  // nothing to declare officer
+}
+
+import { useEffect, useMemo, useRef, useState } from "react";
+import { useIsMounted } from "../useIsMounted/useIsMounted.js";
+
+;// CONCATENATED MODULE: external "react"
+
+;// CONCATENATED MODULE: external "../useIsMounted/useIsMounted.js"
+
+;// CONCATENATED MODULE: ./src/hooks/useResizeObserver/useResizeObserver.ts
+
+
+const defaultState = {
+    x: 0,
+    y: 0,
+    width: 0,
+    height: 0,
+    top: 0,
+    left: 0,
+    bottom: 0,
+    right: 0
+};
+/**
+ * A custom hook that uses the ResizeObserver API to track the size changes of a DOM element.
+ *
+ * @template T - The type of the DOM element being observed.
+ * @param {ResizeObserverOptions} [options] - The options to configure the ResizeObserver.
+ * @returns {[React.RefObject<T>, ObserverRect]} - A tuple containing the ref object and
+ *                                                the observed rectangle.
+ * @example
+ *
+ * const [rightElementRef, rect] = useResizeObserver<HTMLDivElement>();
+ * <div ref={componentRef}>
+ *   Observed: <code>{JSON.stringify(rect)}</code>
+ * </div>
+ */ function useResizeObserver(options) {
+    const isMounted = useIsMounted();
+    const frameID = useRef(0);
+    const ref = useRef(null);
+    const [rect, setRect] = useState(defaultState);
+    const observer = useMemo(()=>{
+        /* v8 ignore start - SSR check for ResizeObserver */ if (typeof ResizeObserver === "undefined") {
+            return null;
+        }
+        /* v8 ignore stop */ return new ResizeObserver((entries)=>{
+            /* v8 ignore start - resize entry handling */ const entry = entries[0];
+            if (entry) {
+                cancelAnimationFrame(frameID.current);
+                frameID.current = requestAnimationFrame(()=>{
+                    if (ref.current && isMounted()) {
+                        setRect(entry.contentRect);
+                    }
+                });
+            }
+        /* v8 ignore stop */ });
+    }, [
+        isMounted
+    ]);
+    useEffect(()=>{
+        /* v8 ignore start - ref.current check */ if (ref.current) {
+            observer?.observe(ref.current, options);
+        }
+        /* v8 ignore stop */ return ()=>{
+            observer?.disconnect();
+            /* v8 ignore start - frameID cleanup */ if (frameID.current) {
+                cancelAnimationFrame(frameID.current);
+            }
+        /* v8 ignore stop */ };
+    }, [
+        observer,
+        options
+    ]);
+    return [
+        ref,
+        rect
+    ];
+}
+
+export { useResizeObserver };

package/dist/useUncontrolled/useUncontrolled.d.ts

@@ -0,0 +1,14 @@
+interface UseUncontrolledInput<T> {
+    /** Value for controlled state */
+    value?: T;
+    /** Initial value for uncontrolled state */
+    defaultValue?: T;
+    /** Final value for uncontrolled state when value and defaultValue are not provided */
+    finalValue?: T;
+    /** Controlled state onChange handler */
+    onChange?: (value: T) => void;
+    /** Initial delay for controlled state */
+    initialControlledDelay?: number;
+}
+export declare function useUncontrolled<T>({ value, defaultValue, finalValue, onChange, initialControlledDelay, }: UseUncontrolledInput<T>): [T, (value: T) => void, boolean];
+export {};

package/dist/useUncontrolled/useUncontrolled.js

@@ -0,0 +1,76 @@
+/*!
+  @versini/ui-hooks v6.0.1
+  © 2025 gizmette.com
+*/
+try {
+  if (!window.__VERSINI_UI_HOOKS__) {
+    window.__VERSINI_UI_HOOKS__ = {
+      version: "6.0.1",
+      buildTime: "12/24/2025 09:19 AM EST",
+      homepage: "https://www.npmjs.com/package/@versini/ui-hooks",
+      license: "MIT",
+    };
+  }
+} catch (error) {
+  // nothing to declare officer
+}
+
+import { useEffect, useState } from "react";
+
+;// CONCATENATED MODULE: external "react"
+
+;// CONCATENATED MODULE: ./src/hooks/useUncontrolled/useUncontrolled.ts
+
+function useUncontrolled({ value, defaultValue, finalValue, onChange = ()=>{}, initialControlledDelay = 0 }) {
+    const [initialDelayDone, setInitialDelayDone] = useState(false);
+    const [uncontrolledValue, setUncontrolledValue] = useState(defaultValue !== undefined ? defaultValue : finalValue);
+    const handleUncontrolledChange = (val)=>{
+        setUncontrolledValue(val);
+        onChange?.(val);
+    };
+    useEffect(()=>{
+        (async ()=>{
+            /**
+			 * If initialControlledDelay is provided, wait for the delay.
+			 */ if (value !== undefined) {
+                /* c8 ignore start */ if (!initialDelayDone && initialControlledDelay > 0) {
+                    await new Promise((resolve)=>setTimeout(resolve, initialControlledDelay));
+                    setInitialDelayDone(true);
+                }
+            /* c8 ignore end */ }
+        })();
+    }, [
+        value,
+        initialControlledDelay,
+        initialDelayDone
+    ]);
+    /**
+	 * If value is provided, return the controlled value.
+	 * If there is a delay, we need to wait for the delay: we need to first send
+	 * back a value of an empty string, then after the delay
+	 * we can send the actual value.
+	 */ if (value !== undefined) {
+        if (!initialDelayDone && initialControlledDelay > 0) {
+            return [
+                "",
+                onChange,
+                true
+            ];
+        } else {
+            return [
+                value,
+                onChange,
+                true
+            ];
+        }
+    }
+    /**
+	 * If value is not provided, return the uncontrolled value.
+	 */ return [
+        uncontrolledValue,
+        handleUncontrolledChange,
+        false
+    ];
+}
+
+export { useUncontrolled };

package/dist/useUniqueId/useUniqueId.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Hook that generates a unique id that will retain its value
+ * during the lifecycle of the calling functional component.
+ *
+ * The parameters are either
+ * - nothing: a unique id will simply be generated with no prefix.
+ * - a string or a number: a prefix to prepend to the generated id.
+ * - an object with the following props:
+ *    - id: if this is a number or a string, it will be returned as is
+ *    - prefix: prefix to prepend to the generated id.
+ *
+ * @param {string | number | object} options
+ * @returns a unique id
+ *
+ * @examples
+ *
+ * const someId = useUniqueId();
+ * // -> someId = "1j3h4f5"
+ *
+ * const errorId = useUniqueId("av-text-input-error-");
+ * // -> errorId = "av-text-input-error-1j3h4f5"
+ *
+ * const inputId = useUniqueId({ id: 42, prefix: "av-text-input-" });
+ * // -> inputId = "av-text-input-42"
+ *
+ * const inputHintId = useUniqueId({
+ *   prefix: "av-text-input-hint-",
+ * });
+ * // -> inputHintId = "av-text-input-hint-1j3h4f5"
+ *
+ */
+export type UseUniqueIdOptions = string | number | {
+    id?: string | number;
+    prefix?: string;
+};
+export declare function useUniqueId(options?: UseUniqueIdOptions): string | undefined;

package/dist/useUniqueId/useUniqueId.js

@@ -0,0 +1,41 @@
+/*!
+  @versini/ui-hooks v6.0.1
+  © 2025 gizmette.com
+*/
+try {
+  if (!window.__VERSINI_UI_HOOKS__) {
+    window.__VERSINI_UI_HOOKS__ = {
+      version: "6.0.1",
+      buildTime: "12/24/2025 09:19 AM EST",
+      homepage: "https://www.npmjs.com/package/@versini/ui-hooks",
+      license: "MIT",
+    };
+  }
+} catch (error) {
+  // nothing to declare officer
+}
+
+import { useId } from "react";
+
+;// CONCATENATED MODULE: external "react"
+
+;// CONCATENATED MODULE: ./src/hooks/useUniqueId/useUniqueId.ts
+
+function useUniqueId(options) {
+    const generatedId = useId();
+    if (!options) {
+        return generatedId;
+    }
+    if (typeof options === "number" || typeof options === "string") {
+        return `${options}${generatedId}`;
+    }
+    /* v8 ignore start - object options edge case */ if (typeof options === "object") {
+        const { id, prefix = "" } = options;
+        if (typeof id === "number" || typeof id === "string") {
+            return `${prefix}${id}`;
+        }
+        return `${prefix}${generatedId}`;
+    }
+/* v8 ignore stop */ }
+
+export { useUniqueId };

package/dist/useViewportSize/useViewportSize.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Custom hook that returns the current viewport size. It will update
+ * when the window is resized or the orientation changes.
+ *
+ * @returns The current viewport size
+ *
+ * @example
+ * const { width, height } = useViewportSize();
+ */
+export declare function useViewportSize(): {
+    width: number;
+    height: number;
+};

package/dist/useViewportSize/useViewportSize.js

@@ -0,0 +1,60 @@
+/*!
+  @versini/ui-hooks v6.0.1
+  © 2025 gizmette.com
+*/
+try {
+  if (!window.__VERSINI_UI_HOOKS__) {
+    window.__VERSINI_UI_HOOKS__ = {
+      version: "6.0.1",
+      buildTime: "12/24/2025 09:19 AM EST",
+      homepage: "https://www.npmjs.com/package/@versini/ui-hooks",
+      license: "MIT",
+    };
+  }
+} catch (error) {
+  // nothing to declare officer
+}
+
+import { useCallback, useEffect, useState } from "react";
+
+;// CONCATENATED MODULE: external "react"
+
+;// CONCATENATED MODULE: ./src/hooks/useViewportSize/useViewportSize.tsx
+
+function useWindowEvent(type, listener) {
+    useEffect(()=>{
+        window.addEventListener(type, listener, {
+            passive: true
+        });
+        return ()=>window.removeEventListener(type, listener);
+    }, [
+        type,
+        listener
+    ]);
+}
+/**
+ * Custom hook that returns the current viewport size. It will update
+ * when the window is resized or the orientation changes.
+ *
+ * @returns The current viewport size
+ *
+ * @example
+ * const { width, height } = useViewportSize();
+ */ function useViewportSize() {
+    const [windowSize, setWindowSize] = useState({
+        width: 0,
+        height: 0
+    });
+    const setSize = useCallback(()=>{
+        setWindowSize({
+            width: window.innerWidth || 0,
+            height: window.innerHeight || 0
+        });
+    }, []);
+    useWindowEvent("resize", setSize);
+    useWindowEvent("orientationchange", setSize);
+    useEffect(setSize, []);
+    return windowSize;
+}
+
+export { useViewportSize };

package/dist/useVisualViewportSize/useVisualViewportSize.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Custom hook that returns the current visual viewport size. It will update
+ * when the window is resized (zoom, virtual keyboard displayed, etc.) or
+ * the orientation changes.
+ *
+ * @returns The current visual viewport size
+ *
+ * @example
+ * const { width, height } = useVisualViewportSize();
+ */
+export declare function useVisualViewportSize(): {
+    width: number;
+    height: number;
+};

package/dist/useVisualViewportSize/useVisualViewportSize.js

@@ -0,0 +1,70 @@
+/*!
+  @versini/ui-hooks v6.0.1
+  © 2025 gizmette.com
+*/
+try {
+  if (!window.__VERSINI_UI_HOOKS__) {
+    window.__VERSINI_UI_HOOKS__ = {
+      version: "6.0.1",
+      buildTime: "12/24/2025 09:19 AM EST",
+      homepage: "https://www.npmjs.com/package/@versini/ui-hooks",
+      license: "MIT",
+    };
+  }
+} catch (error) {
+  // nothing to declare officer
+}
+
+import { useCallback, useEffect, useState } from "react";
+
+;// CONCATENATED MODULE: external "react"
+
+;// CONCATENATED MODULE: ./src/hooks/useVisualViewportSize/useVisualViewportSize.tsx
+/* v8 ignore start */ 
+/**
+ * Custom hook that returns the current visual viewport size. It will update
+ * when the window is resized (zoom, virtual keyboard displayed, etc.) or
+ * the orientation changes.
+ *
+ * @returns The current visual viewport size
+ *
+ * @example
+ * const { width, height } = useVisualViewportSize();
+ */ function useVisualViewportSize() {
+    const [windowSize, setWindowSize] = useState({
+        width: 0,
+        height: 0
+    });
+    // Define setSize function once and never recreate it
+    const setSize = useCallback(()=>{
+        setWindowSize({
+            width: window?.visualViewport?.width || window.innerWidth || 0,
+            height: window?.visualViewport?.height || window.innerHeight || 0
+        });
+    }, []); // Empty dependency array is correct here
+    useEffect(()=>{
+        // Initial size setup
+        setSize();
+        // Set up event listeners
+        if (window.visualViewport) {
+            window.visualViewport.addEventListener("resize", setSize, {
+                passive: true
+            });
+            window.visualViewport.addEventListener("orientationchange", setSize, {
+                passive: true
+            });
+        }
+        // Cleanup
+        return ()=>{
+            if (window.visualViewport) {
+                window.visualViewport.removeEventListener("resize", setSize);
+                window.visualViewport.removeEventListener("orientationchange", setSize);
+            }
+        };
+    }, [
+        setSize
+    ]);
+    return windowSize;
+} /* v8 ignore end */ 
+
+export { useVisualViewportSize };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@versini/ui-hooks",
-	"version": "5.3.2",
+	"version": "6.0.1",
 	"license": "MIT",
 	"author": "Arno Versini",
 	"publishConfig": {
@@ -12,8 +12,60 @@
 		"url": "git@github.com:aversini/ui-components.git"
 	},
 	"type": "module",
-	"main": "dist/index.js",
-	"types": "dist/index.d.ts",
+	"exports": {
+		"./use-click-outside": {
+			"types": "./dist/useClickOutside/useClickOutside.d.ts",
+			"import": "./dist/useClickOutside/useClickOutside.js"
+		},
+		"./use-haptic": {
+			"types": "./dist/useHaptic/useHaptic.d.ts",
+			"import": "./dist/useHaptic/useHaptic.js"
+		},
+		"./use-hotkeys": {
+			"types": "./dist/useHotkeys/useHotkeys.d.ts",
+			"import": "./dist/useHotkeys/useHotkeys.js"
+		},
+		"./use-interval": {
+			"types": "./dist/useInterval/useInterval.d.ts",
+			"import": "./dist/useInterval/useInterval.js"
+		},
+		"./use-in-viewport": {
+			"types": "./dist/useInViewport/useInViewport.d.ts",
+			"import": "./dist/useInViewport/useInViewport.js"
+		},
+		"./use-is-mounted": {
+			"types": "./dist/useIsMounted/useIsMounted.d.ts",
+			"import": "./dist/useIsMounted/useIsMounted.js"
+		},
+		"./use-local-storage": {
+			"types": "./dist/useLocalStorage/useLocalStorage.d.ts",
+			"import": "./dist/useLocalStorage/useLocalStorage.js"
+		},
+		"./use-merge-refs": {
+			"types": "./dist/useMergeRefs/useMergeRefs.d.ts",
+			"import": "./dist/useMergeRefs/useMergeRefs.js"
+		},
+		"./use-resize-observer": {
+			"types": "./dist/useResizeObserver/useResizeObserver.d.ts",
+			"import": "./dist/useResizeObserver/useResizeObserver.js"
+		},
+		"./use-uncontrolled": {
+			"types": "./dist/useUncontrolled/useUncontrolled.d.ts",
+			"import": "./dist/useUncontrolled/useUncontrolled.js"
+		},
+		"./use-unique-id": {
+			"types": "./dist/useUniqueId/useUniqueId.d.ts",
+			"import": "./dist/useUniqueId/useUniqueId.js"
+		},
+		"./use-viewport-size": {
+			"types": "./dist/useViewportSize/useViewportSize.d.ts",
+			"import": "./dist/useViewportSize/useViewportSize.js"
+		},
+		"./use-visual-viewport-size": {
+			"types": "./dist/useVisualViewportSize/useVisualViewportSize.d.ts",
+			"import": "./dist/useVisualViewportSize/useVisualViewportSize.js"
+		}
+	},
 	"files": [
 		"dist",
 		"README.md"
@@ -36,5 +88,5 @@
 		"test:watch": "vitest",
 		"test": "vitest run"
 	},
-	"gitHead": "ef4323fa1f14f9f2a5471d71f063519230762aec"
+	"gitHead": "7b2640a0650a4c3aa6ca078888f765cb400f9f13"
 }