@versini/ui-hooks 5.3.2 → 6.0.1

package/dist/useInViewport/useInViewport.js

@@ -0,0 +1,52 @@
+/*!
+  @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, useRef, useState } from "react";
+
+;// CONCATENATED MODULE: external "react"
+
+;// CONCATENATED MODULE: ./src/hooks/useInViewport/useInViewport.ts
+
+/**
+ * Hook that checks if an element is visible in the viewport.
+ * @returns
+ * ref: React ref object to attach to the element you want to monitor.
+ * inViewport: Boolean indicating if the element is in the viewport.
+ */ /* v8 ignore start */ function useInViewport() {
+    const observer = useRef(null);
+    const [inViewport, setInViewport] = useState(false);
+    const ref = useCallback((node)=>{
+        if (typeof IntersectionObserver !== "undefined") {
+            if (node && !observer.current) {
+                observer.current = new IntersectionObserver((entries)=>setInViewport(entries.some((entry)=>entry.isIntersecting)));
+            } else {
+                observer.current?.disconnect();
+            }
+            if (node) {
+                observer.current?.observe(node);
+            } else {
+                setInViewport(false);
+            }
+        }
+    }, []);
+    return {
+        ref,
+        inViewport
+    };
+} /* v8 ignore stop */ 
+
+export { useInViewport };

package/dist/useInterval/useInterval.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Custom hook to call a function within a given interval.
+ *
+ * @param fn Callback function to be executed at each interval
+ * @param interval  Interval time in milliseconds
+ * @returns An object containing start, stop, and active state
+ *
+ * @example
+ * const { start, stop, active } = useInterval(() => {
+ *  console.log("Interval executed");
+ * }, 1000);
+ * start(); // To start the interval
+ * stop(); // To stop the interval
+ * console.log(active); // To check if the interval is active
+ *
+ */
+export declare function useInterval(fn: () => void, interval: number): {
+    start: () => void;
+    stop: () => void;
+    active: boolean;
+};

package/dist/useInterval/useInterval.js

@@ -0,0 +1,75 @@
+/*!
+  @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, useRef, useState } from "react";
+
+;// CONCATENATED MODULE: external "react"
+
+;// CONCATENATED MODULE: ./src/hooks/useInterval/useInterval.ts
+
+/**
+ * Custom hook to call a function within a given interval.
+ *
+ * @param fn Callback function to be executed at each interval
+ * @param interval  Interval time in milliseconds
+ * @returns An object containing start, stop, and active state
+ *
+ * @example
+ * const { start, stop, active } = useInterval(() => {
+ *  console.log("Interval executed");
+ * }, 1000);
+ * start(); // To start the interval
+ * stop(); // To stop the interval
+ * console.log(active); // To check if the interval is active
+ *
+ */ function useInterval(fn, interval) {
+    const [active, setActive] = useState(false);
+    const intervalRef = useRef(null);
+    const fnRef = useRef(null);
+    const start = useCallback(()=>{
+        setActive((old)=>{
+            /* v8 ignore start - interval reactivation edge case */ if (!old && (!intervalRef.current || intervalRef.current === -1)) {
+                intervalRef.current = window.setInterval(fnRef.current, interval);
+            }
+            /* v8 ignore stop */ return true;
+        });
+    }, [
+        interval
+    ]);
+    const stop = useCallback(()=>{
+        setActive(false);
+        window.clearInterval(intervalRef.current || -1);
+        intervalRef.current = -1;
+    }, []);
+    useEffect(()=>{
+        fnRef.current = fn;
+        active && start();
+        return stop;
+    }, [
+        fn,
+        active,
+        start,
+        stop
+    ]);
+    return {
+        start,
+        stop,
+        active
+    };
+}
+
+export { useInterval };

package/dist/useIsMounted/useIsMounted.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Custom hook that returns a function indicating whether the component
+ * is mounted or not.
+ *
+ * @returns A function that returns a boolean value indicating whether
+ *          the component is mounted.
+ *
+ * @example
+ * const isMounted = useIsMounted();
+ * console.log(isMounted()); // true
+ *
+ */
+export declare function useIsMounted(): () => boolean;

package/dist/useIsMounted/useIsMounted.js

@@ -0,0 +1,46 @@
+/*!
+  @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, useRef } from "react";
+
+;// CONCATENATED MODULE: external "react"
+
+;// CONCATENATED MODULE: ./src/hooks/useIsMounted/useIsMounted.ts
+
+/**
+ * Custom hook that returns a function indicating whether the component
+ * is mounted or not.
+ *
+ * @returns A function that returns a boolean value indicating whether
+ *          the component is mounted.
+ *
+ * @example
+ * const isMounted = useIsMounted();
+ * console.log(isMounted()); // true
+ *
+ */ function useIsMounted() {
+    const isMounted = useRef(false);
+    useEffect(()=>{
+        isMounted.current = true;
+        return ()=>{
+            isMounted.current = false;
+        };
+    }, []);
+    return useCallback(()=>isMounted.current, []);
+}
+
+export { useIsMounted };

package/dist/useLocalStorage/useLocalStorage.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Configuration properties for the useLocalStorage hook.
+ *
+ * @template T - The type of the value stored in localStorage
+ *
+ */
+export interface StorageProperties<T> {
+    /**
+     * The localStorage key under which the value will be stored. Must be unique
+     * within your application to avoid conflicts.
+     */
+    key: string;
+    /**
+     * Optional default value that will be set in localStorage if no value exists.
+     * This value will be used on initial mount and when resetValue() is called.
+     */
+    initialValue?: T;
+}
+/**
+ * A React hook for managing state synchronized with localStorage. Uses React
+ * 19's useSyncExternalStore for optimal concurrent rendering support and
+ * automatic synchronization across components. Changes are automatically
+ * persisted to localStorage and synchronized across all components using the
+ * same key, including across browser tabs.
+ *
+ * Features:
+ * - Automatic serialization/deserialization with JSON
+ * - Type-safe with TypeScript generics
+ * - Supports functional updates (similar to setState)
+ * - Synchronized across components and browser tabs
+ * - Handles edge cases (null, undefined, errors)
+ * - Compatible with React 19+ concurrent features
+ *
+ * @template T - The type of the value stored in localStorage
+ * @param {StorageProperties<T>} config - Configuration object with key and optional initialValue
+ * @returns {[T | null, (value: T | ((current: T) => T)) => void, () => void, () => void]} A tuple containing:
+ *   - [0] current value from localStorage (or null if not set)
+ *   - [1] setValue function to update the stored value (supports direct value or function updater)
+ *   - [2] resetValue function to restore the initialValue
+ *   - [3] removeValue function to remove the value from localStorage
+ *
+ * @example
+ * ```js
+ * // Basic usage with a string value
+ * import { useLocalStorage } from '@versini/ui-hooks';
+ * const [model, setModel, resetModel, removeModel] = useLocalStorage({
+ *   key: 'gpt-model',
+ *   initialValue: 'gpt-3',
+ * });
+ *
+ * // Direct update
+ * setModel('gpt-4'); // Stores "gpt-4"
+ *
+ * // Functional update (receives current value)
+ * setModel((current) => (current === 'gpt-3' ? 'gpt-4' : 'gpt-3'));
+ *
+ * // Reset to initial value
+ * resetModel(); // Restores "gpt-3"
+ *
+ * // Remove from localStorage
+ * removeModel(); // Sets value to null and removes from storage
+ * ```
+ *
+ * @example
+ * ```js
+ * // Usage with complex objects
+ * interface UserPreferences {
+ *   theme: 'light' | 'dark';
+ *   fontSize: number;
+ * }
+ *
+ * const [prefs, setPrefs] = useLocalStorage<UserPreferences>({
+ *   key: 'user-preferences',
+ *   initialValue: { theme: 'light', fontSize: 14 }
+ * });
+ *
+ * // Update specific property
+ * setPrefs(current => ({ ...current, theme: 'dark' }));
+ * ```
+ *
+ */
+export declare function useLocalStorage<T>({ key, initialValue, }: StorageProperties<T>): any[];

package/dist/useLocalStorage/useLocalStorage.js

@@ -0,0 +1,236 @@
+/*!
+  @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, useSyncExternalStore } from "react";
+
+;// CONCATENATED MODULE: external "react"
+
+;// CONCATENATED MODULE: ./src/hooks/useLocalStorage/useLocalStorage.ts
+
+/**
+ * Dispatches a custom storage event to notify other parts of the application
+ * about localStorage changes. This is necessary because the native storage
+ * event only fires in other tabs/windows, not in the current one. By manually
+ * dispatching the event, we ensure that all components using the same key stay
+ * synchronized.
+ *
+ * @param key - The localStorage key that was modified
+ * @param newValue - The new value (stringified) or null if the item was removed
+ *
+ */ function dispatchStorageEvent(key, newValue) {
+    window.dispatchEvent(new StorageEvent("storage", {
+        key,
+        newValue
+    }));
+}
+/**
+ * Sets an item in localStorage and dispatches a storage event. Handles both
+ * direct values and function updaters (similar to React's setState). Values are
+ * automatically serialized to JSON before storage.
+ *
+ * @param key - The localStorage key to set
+ * @param value - The value to store, or a function that returns the value to store
+ *
+ */ const setLocalStorageItem = (key, value)=>{
+    /**
+	 * If value is a function, call it to get the actual value (supports functional
+	 * updates).
+	 */ const stringifiedValue = JSON.stringify(typeof value === "function" ? value() : value);
+    window.localStorage.setItem(key, stringifiedValue);
+    // Dispatch event to notify other components in the same window/tab.
+    dispatchStorageEvent(key, stringifiedValue);
+};
+/**
+ * Removes an item from localStorage and dispatches a storage event with null
+ * value. This ensures all components using this key are notified of the
+ * removal.
+ *
+ * @param key - The localStorage key to remove
+ *
+ */ const removeLocalStorageItem = (key)=>{
+    window.localStorage.removeItem(key);
+    // Dispatch event with null to signal removal.
+    dispatchStorageEvent(key, null);
+};
+/**
+ * Retrieves an item from localStorage. Returns the raw stringified value or
+ * null if the key doesn't exist.
+ *
+ * @param key - The localStorage key to retrieve
+ * @returns The stored string value or null if not found
+ *
+ */ const getLocalStorageItem = (key)=>{
+    return window.localStorage.getItem(key);
+};
+/**
+ * Creates a subscription to localStorage changes for use with React's
+ * useSyncExternalStore. This function is called by React to set up and tear
+ * down event listeners. It listens to both native storage events (from other
+ * tabs) and custom dispatched events (from this tab).
+ *
+ * @param callback - The callback function to invoke when storage changes occur
+ * @returns A cleanup function that removes the event listener
+ *
+ */ const useLocalStorageSubscribe = (callback)=>{
+    window.addEventListener("storage", callback);
+    // Return cleanup function for React to call on unmount.
+    return ()=>window.removeEventListener("storage", callback);
+};
+/**
+ * A React hook for managing state synchronized with localStorage. Uses React
+ * 19's useSyncExternalStore for optimal concurrent rendering support and
+ * automatic synchronization across components. Changes are automatically
+ * persisted to localStorage and synchronized across all components using the
+ * same key, including across browser tabs.
+ *
+ * Features:
+ * - Automatic serialization/deserialization with JSON
+ * - Type-safe with TypeScript generics
+ * - Supports functional updates (similar to setState)
+ * - Synchronized across components and browser tabs
+ * - Handles edge cases (null, undefined, errors)
+ * - Compatible with React 19+ concurrent features
+ *
+ * @template T - The type of the value stored in localStorage
+ * @param {StorageProperties<T>} config - Configuration object with key and optional initialValue
+ * @returns {[T | null, (value: T | ((current: T) => T)) => void, () => void, () => void]} A tuple containing:
+ *   - [0] current value from localStorage (or null if not set)
+ *   - [1] setValue function to update the stored value (supports direct value or function updater)
+ *   - [2] resetValue function to restore the initialValue
+ *   - [3] removeValue function to remove the value from localStorage
+ *
+ * @example
+ * ```js
+ * // Basic usage with a string value
+ * import { useLocalStorage } from '@versini/ui-hooks';
+ * const [model, setModel, resetModel, removeModel] = useLocalStorage({
+ *   key: 'gpt-model',
+ *   initialValue: 'gpt-3',
+ * });
+ *
+ * // Direct update
+ * setModel('gpt-4'); // Stores "gpt-4"
+ *
+ * // Functional update (receives current value)
+ * setModel((current) => (current === 'gpt-3' ? 'gpt-4' : 'gpt-3'));
+ *
+ * // Reset to initial value
+ * resetModel(); // Restores "gpt-3"
+ *
+ * // Remove from localStorage
+ * removeModel(); // Sets value to null and removes from storage
+ * ```
+ *
+ * @example
+ * ```js
+ * // Usage with complex objects
+ * interface UserPreferences {
+ *   theme: 'light' | 'dark';
+ *   fontSize: number;
+ * }
+ *
+ * const [prefs, setPrefs] = useLocalStorage<UserPreferences>({
+ *   key: 'user-preferences',
+ *   initialValue: { theme: 'light', fontSize: 14 }
+ * });
+ *
+ * // Update specific property
+ * setPrefs(current => ({ ...current, theme: 'dark' }));
+ * ```
+ *
+ */ function useLocalStorage({ key, initialValue }) {
+    /**
+	 * Snapshot function for useSyncExternalStore - returns current localStorage
+	 * value.
+	 */ const getSnapshot = ()=>getLocalStorageItem(key);
+    /**
+	 * Use React's useSyncExternalStore to subscribe to localStorage changes. This
+	 * ensures proper integration with React 19+ concurrent rendering and provides
+	 * automatic re-rendering when the stored value changes (either from this
+	 * component, other components, or other browser tabs).
+	 */ const store = useSyncExternalStore(useLocalStorageSubscribe, getSnapshot);
+    /**
+	 * Updates the stored value in localStorage. Accepts either a direct value or a
+	 * function that receives the current value. Setting to null or undefined will
+	 * remove the item from localStorage.
+	 */ const setValue = useCallback((v)=>{
+        try {
+            // Support both direct values and functional updates.
+            const nextState = typeof v === "function" ? v(JSON.parse(store)) : v;
+            // Remove from storage if value is null or undefined.
+            if (nextState === undefined || nextState === null) {
+                removeLocalStorageItem(key);
+            } else {
+                setLocalStorageItem(key, nextState);
+            }
+        /* v8 ignore start */ } catch (e) {
+            // Log parsing or storage errors without breaking the application.
+            console.warn(e);
+        }
+    /* v8 ignore stop */ }, [
+        key,
+        store
+    ]);
+    /**
+	 * Resets the stored value back to the initialValue provided in the
+	 * configuration. If no initialValue was provided, this will remove the item
+	 * from localStorage.
+	 */ const resetValue = useCallback(()=>{
+        setValue(initialValue);
+    }, [
+        initialValue,
+        setValue
+    ]);
+    /**
+	 * Removes the value from localStorage entirely. After calling this, the hook
+	 * will return null until a new value is set.
+	 */ const removeValue = useCallback(()=>{
+        setValue(null);
+    }, [
+        setValue
+    ]);
+    /**
+	 * Initialize localStorage with the initialValue on first mount if the key
+	 * doesn't exist. This effect only runs once when the component mounts and
+	 * ensures that the initialValue is persisted to localStorage if no value is
+	 * currently stored.
+	 */ useEffect(()=>{
+        try {
+            // Only set initialValue if key doesn't exist and initialValue is defined.
+            if (getLocalStorageItem(key) === null && typeof initialValue !== "undefined") {
+                setLocalStorageItem(key, initialValue);
+            }
+        /* v8 ignore start */ } catch (e) {
+            // Log initialization errors without breaking the application.
+            console.warn(e);
+        }
+    /* v8 ignore stop */ }, [
+        key,
+        initialValue
+    ]);
+    /**
+	 * Return tuple: [currentValue, setValue, resetValue, removeValue] Parse the
+	 * stored JSON string back to its original type, or return null if empty.
+	 */ return [
+        store ? JSON.parse(store) : null,
+        setValue,
+        resetValue,
+        removeValue
+    ];
+}
+
+export { useLocalStorage };

package/dist/useMergeRefs/useMergeRefs.d.ts

@@ -0,0 +1,20 @@
+/**
+ * React utility to merge refs.
+ *
+ * When developing low level UI components, it is common to have to use a local
+ * ref but also support an external one using React.forwardRef. Natively, React
+ * does not offer a way to set two refs inside the ref property.
+ *
+ * @param Array of refs (object, function, etc.)
+ *
+ * @example
+ *
+ * const Example = React.forwardRef(function Example(props, ref) {
+ *   const localRef = React.useRef();
+ *   const mergedRefs = useMergeRefs([localRef, ref]);
+ *
+ *   return <div ref={mergedRefs} />;
+ * });
+ *
+ */
+export declare function useMergeRefs<T = any>(refs: Array<React.MutableRefObject<T> | React.LegacyRef<T> | undefined | null>): React.RefCallback<T>;

package/dist/useMergeRefs/useMergeRefs.js

@@ -0,0 +1,62 @@
+/*!
+  @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 { useMemo } from "react";
+
+;// CONCATENATED MODULE: external "react"
+
+;// CONCATENATED MODULE: ./src/hooks/useMergeRefs/useMergeRefs.ts
+/**
+ * React utility to merge refs.
+ *
+ * When developing low level UI components, it is common to have to use a local
+ * ref but also support an external one using React.forwardRef. Natively, React
+ * does not offer a way to set two refs inside the ref property.
+ *
+ * @param Array of refs (object, function, etc.)
+ *
+ * @example
+ *
+ * const Example = React.forwardRef(function Example(props, ref) {
+ *   const localRef = React.useRef();
+ *   const mergedRefs = useMergeRefs([localRef, ref]);
+ *
+ *   return <div ref={mergedRefs} />;
+ * });
+ *
+ */ 
+function useMergeRefs(refs) {
+    // biome-ignore lint/correctness/useExhaustiveDependencies: refs array is used as dependency but spread for proper comparison
+    return useMemo(()=>{
+        /* v8 ignore start - all refs null edge case */ if (refs.every((ref)=>ref == null)) {
+            return ()=>{};
+        }
+        /* v8 ignore stop */ /* v8 ignore start - ref assignment handling */ return (value)=>{
+            refs.forEach((ref)=>{
+                if (typeof ref === "function") {
+                    ref(value);
+                } else if (ref != null) {
+                    ref.current = value;
+                }
+            });
+        };
+    /* v8 ignore stop */ }, [
+        ...refs
+    ]);
+}
+
+export { useMergeRefs };

package/dist/useResizeObserver/useResizeObserver.d.ts

@@ -0,0 +1,17 @@
+type ObserverRect = Omit<DOMRectReadOnly, "toJSON">;
+/**
+ * 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>
+ */
+export declare function useResizeObserver<T extends HTMLElement = any>(options?: ResizeObserverOptions): readonly [import("react").RefObject<T | null>, ObserverRect];
+export {};