@versini/ui-hooks 5.2.0 → 5.3.0

package/dist/index.d.ts

@@ -18,13 +18,21 @@ declare type ObserverRect = Omit<DOMRectReadOnly, "toJSON">;
 
 export declare function shouldFireEvent(event: KeyboardEvent, tagsToIgnore: string[], triggerOnContentEditable?: boolean): boolean;
 
+/**
+ * Configuration properties for the useLocalStorage hook.
+ *
+ * @template T - The type of the value stored in localStorage
+ *
+ */
 export declare interface StorageProperties<T> {
     /**
-     * Storage key.
+     * The localStorage key under which the value will be stored. Must be unique
+     * within your application to avoid conflicts.
      */
     key: string;
     /**
-     * Default value that will be set if value is not found in storage.
+     * 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;
 }
@@ -47,6 +55,39 @@ export declare interface StorageProperties<T> {
  */
 export declare function useClickOutside<T extends HTMLElement = any>(handler: () => void, events?: string[] | null, nodes?: (HTMLElement | null)[]): RefObject<T | null>;
 
+/**
+ * Custom hook for trapping focus within a container element. Implements W3C
+ * WAI-ARIA dialog focus management patterns:
+ * - Tab/Shift+Tab cycles through focusable elements within the container
+ * - Focus is trapped and cannot escape to elements outside
+ * - Initial focus is set based on the initialFocus option
+ *
+ * @see https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/
+ *
+ */
+export declare function useFocusTrap({ enabled, initialFocus, }: UseFocusTrapOptions): UseFocusTrapReturn;
+
+declare interface UseFocusTrapOptions {
+    /**
+     * Whether the focus trap is active.
+     */
+    enabled: boolean;
+    /**
+     * Which element to initially focus when the trap activates. Can be a number
+     * (tabbable index, 0 = first), a ref to an element, or -1 to disable initial
+     * focus.
+     * @default 0
+     */
+    initialFocus?: number | React.RefObject<HTMLElement | null>;
+}
+
+declare interface UseFocusTrapReturn {
+    /**
+     * Ref to attach to the container element that should trap focus.
+     */
+    containerRef: React.RefObject<HTMLDivElement | null>;
+}
+
 /**
  * Custom hook providing imperative haptic feedback for mobile devices. Uses
  * navigator.vibrate when available, falls back to iOS switch element trick for
@@ -122,18 +163,67 @@ export declare function useInViewport<T extends HTMLElement = any>(): {
 export declare function useIsMounted(): () => boolean;
 
 /**
+ * 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 [value, setValue, resetValue, removeValue] = useLocalStorage({
+ * const [model, setModel, resetModel, removeModel] = useLocalStorage({
  *   key: 'gpt-model',
  *   initialValue: 'gpt-3',
  * });
  *
- * setValue('gpt-4'); ==> "gpt-4"
- * setValue((current) => (current === 'gpt-3' ? 'gpt-4' : 'gpt-3'));
- * resetValue(); ==> "gpt-3"
- * removeValue(); ==> null
+ * // 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/index.js

@@ -1,13 +1,13 @@
 /*!
-  @versini/ui-hooks v5.2.0
+  @versini/ui-hooks v5.3.0
   © 2025 gizmette.com
 */
 try {
   if (!window.__VERSINI_UI_HOOKS__) {
     window.__VERSINI_UI_HOOKS__ = {
-      version: "5.2.0",
-      buildTime: "11/04/2025 03:42 PM EST",
-      homepage: "https://github.com/aversini/ui-components",
+      version: "5.3.0",
+      buildTime: "12/14/2025 08:04 PM EST",
+      homepage: "https://www.npmjs.com/package/@versini/ui-hooks",
       license: "MIT",
     };
   }
@@ -65,6 +65,160 @@ const DEFAULT_EVENTS = [
     return ref;
 }
 
+;// CONCATENATED MODULE: ./src/hooks/useFocusTrap.ts
+
+/**
+ * Selector for all focusable elements within a container. Based on W3C WAI-ARIA
+ * practices for dialog focus management.
+ */ const FOCUSABLE_SELECTOR = [
+    'a[href]:not([disabled]):not([tabindex="-1"])',
+    'button:not([disabled]):not([tabindex="-1"])',
+    'textarea:not([disabled]):not([tabindex="-1"])',
+    'input:not([disabled]):not([tabindex="-1"])',
+    'select:not([disabled]):not([tabindex="-1"])',
+    '[tabindex]:not([tabindex="-1"]):not([disabled])',
+    'audio[controls]:not([tabindex="-1"])',
+    'video[controls]:not([tabindex="-1"])',
+    'details:not([tabindex="-1"])'
+].join(", ");
+/**
+ * Custom hook for trapping focus within a container element. Implements W3C
+ * WAI-ARIA dialog focus management patterns:
+ * - Tab/Shift+Tab cycles through focusable elements within the container
+ * - Focus is trapped and cannot escape to elements outside
+ * - Initial focus is set based on the initialFocus option
+ *
+ * @see https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/
+ *
+ */ function useFocusTrap({ enabled, initialFocus = 0 }) {
+    const containerRef = useRef(null);
+    const previouslyFocusedRef = useRef(null);
+    /**
+	 * Get all focusable elements within the container.
+	 */ const getFocusableElements = useCallback(()=>{
+        /* c8 ignore next 3 - defensive check, containerRef is always set when enabled */ if (!containerRef.current) {
+            return [];
+        }
+        const elements = containerRef.current.querySelectorAll(FOCUSABLE_SELECTOR);
+        return Array.from(elements).filter((el)=>el.offsetParent !== null);
+    }, []);
+    /**
+	 * Focus a specific element by index, or the element referenced by a ref.
+	 */ const focusElement = useCallback((target)=>{
+        if (typeof target === "number") {
+            if (target === -1) {
+                // -1 means don't focus anything.
+                return;
+            }
+            const focusableElements = getFocusableElements();
+            if (focusableElements.length > 0) {
+                const index = Math.min(target, focusableElements.length - 1);
+                focusableElements[index]?.focus();
+            }
+        } else if (target?.current) {
+            target.current.focus();
+        }
+    }, [
+        getFocusableElements
+    ]);
+    /**
+	 * Handle keyboard events for focus trapping. Tab cycles forward, Shift+Tab
+	 * cycles backward.
+	 */ const handleKeyDown = useCallback((event)=>{
+        if (event.key !== "Tab" || !containerRef.current) {
+            return;
+        }
+        const activeElement = document.activeElement;
+        // If focus is in a nested dialog, let that dialog handle Tab.
+        if (activeElement && !containerRef.current.contains(activeElement) && activeElement.closest('[role="dialog"]')) {
+            return;
+        }
+        const focusableElements = getFocusableElements();
+        if (focusableElements.length === 0) {
+            event.preventDefault();
+            return;
+        }
+        const firstElement = focusableElements[0];
+        const lastElement = focusableElements[focusableElements.length - 1];
+        // Shift+Tab from first element -> go to last.
+        if (event.shiftKey && activeElement === firstElement) {
+            event.preventDefault();
+            lastElement?.focus();
+            return;
+        }
+        // Tab from last element -> go to first.
+        if (!event.shiftKey && activeElement === lastElement) {
+            event.preventDefault();
+            firstElement?.focus();
+            return;
+        }
+        /* c8 ignore next 9 - defensive check for focus escaping, hard to trigger in tests */ // If focus is outside the container, bring it back.
+        if (!containerRef.current.contains(activeElement)) {
+            event.preventDefault();
+            if (event.shiftKey) {
+                lastElement?.focus();
+            } else {
+                firstElement?.focus();
+            }
+        }
+    }, [
+        getFocusableElements
+    ]);
+    /**
+	 * Handle focus events to ensure focus stays within the container. This catches
+	 * focus that escapes via mouse clicks or other means.
+	 */ const handleFocusIn = useCallback((event)=>{
+        if (!containerRef.current || containerRef.current.contains(event.target)) {
+            return;
+        }
+        // Allow focus to go to nested dialogs (child panels).
+        const target = event.target;
+        if (target?.closest('[role="dialog"]')) {
+            return;
+        }
+        // Focus escaped the container, bring it back.
+        const focusableElements = getFocusableElements();
+        if (focusableElements.length > 0) {
+            focusableElements[0]?.focus();
+        }
+    }, [
+        getFocusableElements
+    ]);
+    // Set up focus trap when enabled.
+    useEffect(()=>{
+        if (!enabled) {
+            return;
+        }
+        // Store the currently focused element to restore later.
+        previouslyFocusedRef.current = document.activeElement;
+        // Set initial focus after a small delay to ensure the DOM is ready.
+        const focusTimer = setTimeout(()=>{
+            focusElement(initialFocus);
+        }, 0);
+        // Add event listeners for focus trapping.
+        document.addEventListener("keydown", handleKeyDown);
+        document.addEventListener("focusin", handleFocusIn);
+        return ()=>{
+            clearTimeout(focusTimer);
+            document.removeEventListener("keydown", handleKeyDown);
+            document.removeEventListener("focusin", handleFocusIn);
+            // Restore focus to the previously focused element if it's still in the DOM.
+            if (previouslyFocusedRef.current?.isConnected) {
+                previouslyFocusedRef.current.focus();
+            }
+        };
+    }, [
+        enabled,
+        initialFocus,
+        focusElement,
+        handleKeyDown,
+        handleFocusIn
+    ]);
+    return {
+        containerRef
+    };
+}
+
 ;// CONCATENATED MODULE: ./src/hooks/useHaptic.ts
 
 const HAPTIC_DURATION_MS = 50;
@@ -460,83 +614,211 @@ function useHotkeys(hotkeys, tagsToIgnore = [
 
 ;// CONCATENATED MODULE: ./src/hooks/useLocalStorage.ts
 
-function dispatchStorageEvent(key, newValue) {
+/**
+ * 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
     }));
 }
-const setLocalStorageItem = (key, value)=>{
-    const stringifiedValue = JSON.stringify(typeof value === "function" ? value() : value);
+/**
+ * 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);
 };
-const removeLocalStorageItem = (key)=>{
+/**
+ * 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);
 };
-const getLocalStorageItem = (key)=>{
+/**
+ * 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);
 };
-const useLocalStorageSubscribe = (callback)=>{
+/**
+ * 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 [value, setValue, resetValue, removeValue] = useLocalStorage({
+ * const [model, setModel, resetModel, removeModel] = useLocalStorage({
  *   key: 'gpt-model',
  *   initialValue: 'gpt-3',
  * });
  *
- * setValue('gpt-4'); ==> "gpt-4"
- * setValue((current) => (current === 'gpt-3' ? 'gpt-4' : 'gpt-3'));
- * resetValue(); ==> "gpt-3"
- * removeValue(); ==> null
+ * // 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 }) {
-    const getSnapshot = ()=>getLocalStorageItem(key);
-    const store = useSyncExternalStore(useLocalStorageSubscribe, getSnapshot);
-    const setValue = useCallback((v)=>{
+    /**
+	 * 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 next 3 */ } catch (e) {
+        /* v8 ignore next 4 */ } catch (e) {
+            // Log parsing or storage errors without breaking the application.
             console.warn(e);
         }
     }, [
         key,
         store
     ]);
-    const resetValue = useCallback(()=>{
+    /**
+	 * 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
     ]);
-    const removeValue = useCallback(()=>{
+    /**
+	 * 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
     ]);
-    useEffect(()=>{
+    /**
+	 * 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 next 3 */ } catch (e) {
+        /* v8 ignore next 4 */ } catch (e) {
+            // Log initialization errors without breaking the application.
             console.warn(e);
         }
     }, [
         key,
         initialValue
     ]);
-    return [
+    /**
+	 * 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,
@@ -827,4 +1109,5 @@ function useWindowEvent(type, listener) {
 
 
 
-export { getHotkeyHandler, shouldFireEvent, useClickOutside, useHaptic, useHotkeys, useInViewport, useInterval, useIsMounted, useLocalStorage, useMergeRefs, useResizeObserver, useUncontrolled, useUniqueId, useViewportSize, useVisualViewportSize };
+
+export { getHotkeyHandler, shouldFireEvent, useClickOutside, useFocusTrap, useHaptic, useHotkeys, useInViewport, useInterval, useIsMounted, useLocalStorage, useMergeRefs, useResizeObserver, useUncontrolled, useUniqueId, useViewportSize, useVisualViewportSize };

package/package.json

@@ -1,12 +1,12 @@
 {
 	"name": "@versini/ui-hooks",
-	"version": "5.2.0",
+	"version": "5.3.0",
 	"license": "MIT",
 	"author": "Arno Versini",
 	"publishConfig": {
 		"access": "public"
 	},
-	"homepage": "https://github.com/aversini/ui-components",
+	"homepage": "https://www.npmjs.com/package/@versini/ui-hooks",
 	"repository": {
 		"type": "git",
 		"url": "git@github.com:aversini/ui-components.git"
@@ -36,5 +36,5 @@
 		"test:watch": "vitest",
 		"test": "vitest run"
 	},
-	"gitHead": "7484ad443b77ef31e52ae3a7d88b8129bc6cdf1d"
+	"gitHead": "15f3028acf21328c70773147a6bedfbafaa3a2a4"
 }