react-hook-toolkit 3.0.5 → 5.0.0

package/README.md

@@ -1,819 +1,289 @@
-
-**react-hook-toolkit** package offers a comprehensive set of hooks to simplify React development. It includes hooks for managing state, handling API requests, optimizing performance, and improving user interactions. Key features include data fetching, form handling, local storage management, debouncing/throttling, window size tracking, event listeners, and more. These hooks are designed to enhance productivity by providing reusable, easy-to-use solutions for common tasks.
-
-**Note : This lightweight and type-safe package is written in TypeScript and offers full support for all hooks across all modern browsers.**
-
-### Installation
-
-Install the package:
-
-```bash
-npm install react-hook-toolkit
-# or
-pnpm add react-hook-toolkit
-```
-
-### **Authors**
-
-![NPM](https://img.shields.io/badge/Author-React_Developers-red)   ![npm](https://img.shields.io/npm/v/react-hook-toolkit?color=1C939D)   ![npm](https://img.shields.io/npm/dt/react-hook-toolkit)   ![NPM](https://img.shields.io/npm/l/react-hook-toolkit)   ![NPM Unpacked Size](https://img.shields.io/npm/unpacked-size/react-hook-toolkit)
-
-### **Browser Support**  
-
-| ![Firefox](https://raw.githubusercontent.com/alrra/browser-logos/main/src/firefox/firefox_48x48.png) | ![Chrome](https://raw.githubusercontent.com/alrra/browser-logos/main/src/chrome/chrome_48x48.png)  | ![Safari](https://raw.githubusercontent.com/alrra/browser-logos/main/src/safari/safari_48x48.png) | ![Opera](https://raw.githubusercontent.com/alrra/browser-logos/main/src/opera/opera_48x48.png) | ![Edge](https://raw.githubusercontent.com/alrra/browser-logos/main/src/edge/edge_48x48.png)
-| ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| Latest ✔                                                                                          | Latest ✔                                                                                             | Latest ✔                                                                                          | Latest ✔                                                                                       | Latest ✔                                                                                    | 
-
-
-###  **Features**
-Here's the properly structured documentation with clear purpose explanations:
-
------------------------------------------- **Custom Hooks**  ------------------------------------------------
-
-📌 **useBrowser**  
-Provides comprehensive browser control and environment detection with a unified API for navigation, window management, and system interactions.
-
-```ts
-const {
-    goBack,
-    goForward,
-    reload,
-    navigateTo,
-    clearBrowserData,
-    historyState,
-    isOnline,
-    copyCurrentUrl,
-    openNewTab,
-    isFullscreen,
-    isShareSupported,
-    closeCurrentTab
-  } = useBrowser();
-```
----
-
-📌 **useRouter**
-Keeps track of the current URL path and query parameters, and allows navigation by updating the browser URL. Useful for lightweight routing in apps without full routing libraries.
-
-```ts
-const { pathname, searchParams, navigate } = useRouter();
-
-console.log(pathname); // "/dashboard"
-
-console.log(searchParams.get("tab")); // "home"
-
-navigate("/dashboard?tab=home");
-```
-
----
-
-📌 **useNavigationState**
-Combines the functionality of `useRouter` and React Router’s `useNavigate` + `useLocation`. Tracks `pathname`, `searchParams`, and `state` (from pushState), and allows navigation while passing custom state.
-
-```ts
-const { pathname, searchParams, state, navigate } = useNavigationState();
-
-console.log(pathname); // "/dashboard"
-
-console.log(searchParams.get("tab")); // "home"
-
-console.log(state?.id); // 34
-
-navigate("/dashboard", { state: { id: 34 } });
-```
-
----
-
-📌 **useRequest**  
-Provides an easy way to fetch data with hooks, managing loading, data, and error states.
-
-```ts
-const { data, loading, error } = useRequest('/api/data');
-```
----
-  📌 **useRequestRetry**  
-Performs an HTTP request with retry logic, retrying a specified number of times upon failure before returning an error.
-
-```ts
-const { data, loading, error } = useRequestRetry('/api/user', { method: 'GET' }, 3);
-```
----
-  📌 **useAsync**  
-Handles the state of an asynchronous function, including loading, success, and error states, with the ability to trigger the execution of the async operation.
-
-```ts
-const { execute, status, value, error } = useAsync(fetchUser);
-
-execute(); // ➝ runs the async function
-```
----
-  📌 **useDebounce**  
-Delays updating the state until after a specified delay, useful for preventing frequent updates (e.g., handling user input).
-
-```ts
-const debouncedSearch = useDebounce(searchText, 500);
-```
-
----
-  📌 **useDebouncedCallback**  
-Delays the execution of a callback function until after a specified delay, resetting the delay on each call to prevent frequent execution.
-
-```ts
-const debounced = useDebouncedCallback(() => search(input), 300);
-
-input.onChange = debounced;
-```
----
-📌 **useDebouncedValue**  
-Returns a debounced version of a value.
-
-```ts
-const debouncedValue = useDebouncedValue(value, 300);
-```
----
-  📌 **useThrottle**  
-Limits how often a value updates within a given time interval, useful for performance optimization.
-
-```ts
-const throttledScroll = useThrottle(scrollValue, 300);
-```
-
----
-  📌 **useDelay**  
-Delays the update of a value for a specified amount of time before reflecting it in the state.
-
-```ts
-const delayedValue = useDelay(value, 500);
-```
----
-  📌 **useTimer**  
-Starts a countdown timer that updates the time every second, returning the current time and any errors.
-
-```ts
-const { time, error } = useTimer(60); // starts from 60 and counts down
-```
----
-  📌 **useInterval**  
-Runs a callback function at a specified time interval and clears it when the delay is null or the component unmounts.
-
-```ts
-useInterval(() => {
-  console.log('Tick');
-}, 1000);
-```
----
-  📌 **useTimeout**  
-Executes a function after a specified delay and cleans up automatically when dependencies change.
-
-```ts
-useTimeout(() => {
-  console.log('Time\'s up!');
-}, 2000);
-```
-
----
-
-  📌 **useForm**  
-Manages form state, handles input changes, and performs validation using provided validators.
-
-```ts
-const { values, errors, handleChange, validate } = useForm({ name: '', email: '' });
-
-handleChange('name', 'John');
-
-validate({
-  name: (val) => (!val ? 'Required' : null),
-  email: (val) => (!val.includes('@') ? 'Invalid email' : null),
-});
-```
----
-📌 **useFormSubmit**  
- Handles form submission with loading/error states and success callbacks.
-
-```ts
-const { submit, isLoading, error } = useFormSubmit(apiCall, {
-  onSuccess: (data) => console.log('Saved!', data)
-});
-
-// Example
-submit(formData);
-```
----
-📌 **useSmartForm**  
- Complete form management with validation, submission, and state handling.
-
-```ts
-const { register, handleSubmit, errors } = useSmartForm({
-  initialValues,
-  validationSchema,
-  onSubmit: (data) => console.log(data)
-});
-
-// Example
-<input {...register('email') />
-<button onClick={handleSubmit}>Save</button>
-```
----
-📌 **useCrossFieldValidation**  
- Handles complex validation rules that depend on multiple fields.
-
-```ts
-const { errors, validate } = useCrossFieldValidation({
-  rules: {
-    password: (val, { confirmPassword }) => val === confirmPassword,
-  },
-  initialValues
-});
-
-// Example
-validate('password', 'secret123', { confirmPassword: 'secret123' });
-```
-
----
-
-📌 **useFieldArray**  
- Manages dynamic arrays of form fields with add/remove/reorder operations.
-
-```ts
-const { fields, append, remove, move } = useFieldArray(initialItems);
-
-// Example
-append({ name: '', email: '' });
-remove(0); // Remove first item
-move(1, 0); // Move second item to first position
-```
----
-📌 **useFormWizard**  
- Manages multi-step forms with navigation between steps.
-
-```ts
-const { currentStep, next, prev, goto } = useFormWizard(steps.length);
-
-// Example
-next(); // Move to next step
-goto(3); // Jump to step 4
-```
-
----
- 📌 **usePersistedForm**  
- Automatically persists form state to localStorage/sessionStorage and restores it on page reload.
-
-```ts
-const { values, setField, reset } = usePersistedForm('form-key', initialValues);
-
-// Example
-setField('username', 'john_doe'); // Auto-saves to storage
-reset(); // Clears storage
-```
-
-
----
-
-  📌 **useEventListener**  
-Listens for a specified event on an element or window, and triggers the handler function when the event is fired. It ensures proper cleanup when the component is unmounted.
-
-```ts
-useEventListener('resize', (e) => {
-  console.log('Window resized');
-});
-```
----
-📌 **useEventListeners**  
- Simplifies adding/removing event listeners.
-
-```ts
-useEventListeners({
-  click: handleClick,
-  resize: handleResize
-});
-
-// Example
-useEventListeners({
-  keydown: (e) => console.log(e.key)
-});
-```
----
-  📌 **useKeyPress**  
-Detects whether a specific key is being pressed or released.
-
-```ts
-const isEnterPressed = useKeyPress('Enter');
-```
----
-📌 **useLongPress**  
- Detects long press gestures.
-
-```ts
-const handlers = useLongPress(() => console.log('Long pressed!'), {
-  threshold: 1000
-});
-
-// Example
-<button {...handlers}>Hold me</button>
-```
----
-  📌 **useTouch**  
-Tracks touch events on a given DOM element, returning the touch positions for `touchstart`, `touchmove`, and `touchend`.
-
-```ts
-const ref = useRef(null);
-const {
-  touchStart,
-  touchMove,
-  touchEnd
-} = useTouch(ref);
-
-<div ref={ref}>Swipe here</div>
-```
----
-📌 **useIdle**  
- Detects when user becomes inactive.
-
-```ts
-const isIdle = useIdle(30000); // 30s timeout
-
-// Example
-{isIdle && <ScreenSaver />}
-```
----
-📌 **useDragReorder**  
- Enables drag-and-drop reordering of lists.
-
-```ts
-const { items, dragStart, dragOver, drop } = useDragReorder(initialItems);
-
-// Example
-<div 
-  draggable 
-  onDragStart={() => dragStart(index)}
-  onDragOver={() => dragOver(index)}
-  onDrop={drop}
-/>
-```
-
----
-
-  📌 **useToggle**  
-A simple boolean toggle hook that returns a state and a function to toggle its value.
-
-```ts
-const [isOpen, toggle] = useToggle(false);
-```
----
-  📌 **useArray**
-Provides an array state with helper functions to manipulate it, including setting, adding, removing by index, and clearing elements.
-
-```ts
-const { array, set, push, removeByIndex, clear } = useArray([1, 2, 3]);
-
-push(4);            // ➝ [1, 2, 3, 4]
-removeByIndex(1);   // ➝ [1, 3, 4]
-clear();            // ➝ []
-```
----
-  📌 **useStepper**  
-Manages step-based navigation by keeping track of the current step index and providing functions to move forward, backward, and reset.
-
-```ts
-const { activeStep, handleNext, handleBack, handleReset, isFirstStep, isLastStep } = useStepper(5);
-
-handleNext(); // ➝ advances step
-handleBack(); // ➝ goes back
-handleReset(); // ➝ step 0
-```
-
-📌 **useDrawer**
-Provides global drawer state and controls to open/close the drawer and manage the current selected main menu, including support for button-triggered toggling.
-
-```ts
-const {
-  drawerOpen,              
-  openDrawer,              
-  closeDrawer,            
-  openDrawerInButton,      
-  closeDrawerInButton,     
-  currentMainMenu,
-  setCurrentMainMenu,  
-} = useContext();
-```
-
----
-📌 **useUndo**  
- Provides undo/redo functionality for state changes.
-
-```ts
-const { state, setState, undo, redo } = useUndo(initialState);
-
-// Example
-setState({ items: [...] });
-undo(); // Reverts to previous state
-```
----
-  📌 **useGenericReducer**  
-A custom reducer function that takes an `initialState` and an object of actions, returning a new state based on the action type. 
-
-```ts
-const reducer = useGenericReducer(initialState, {
-  increment: (state) => ({ count: state.count + 1 }),
-});
-const [state, dispatch] = useReducer(reducer, initialState);
-```
----
-  📌 **useIsMounted**  
-Tracks whether the component is mounted or unmounted, returning a boolean value indicating the component's mount status.
-
-```ts
-const isMounted = useIsMounted();
-```
----
-📌 **useIsFirstRender**  
- Returns true only on component's first render.
-
-```ts
-const isFirst = useIsFirstRender();
-
-// Example
-useEffect(() => {
-  if (!isFirst) console.log('Updated!');
-}, [deps]);
-```
----
-📌 **usePrevious**  
-Tracks the previous value of a state or prop.
-
-```ts
-const previousValue = usePrevious(currentValue);
-```
----
-  📌 **useUpdateEffect**  
-Executes a side effect on updates after the initial render, skipping the effect during the first render to avoid unnecessary executions.
-
-```ts
-useUpdateEffect(() => {
-  console.log("This runs only on updates.");
-}, [value]);
-```
----
-
-📌 **useList**  
- Manages array state with utility methods.
-
-```ts
-const { list, push, remove, update } = useList(initialItems);
-
-// Example
-push(newItem);
-remove(0); // Remove first item
-```
-
----
-
-  📌 **useLocalStorage**  
- A hook to persist state in `localStorage`. It initializes state from `localStorage` and updates it whenever the value changes.
-
-```ts
-const [token, setToken] = useLocalStorage('authToken', '');
-```
----
-  📌 **useSessionStorage**  
-Stores and retrieves data from the `sessionStorage` API, persisting the data during the session. It provides a getter and setter for session-based data.
-
-```ts
-const [value, setValue] = useSessionStorage("myKey", "default");
-
-setValue("newValue");
-console.log(value);
-```
-
----
-  📌 **useCookie**  
-Manages cookies by providing functions to get, set, and delete a specific cookie by its key.
-
-```ts
-const [token, setToken, deleteToken] = useCookie('token');
-
-setToken('abc123');
-deleteToken();
-```
----
-  📌 **usePersistedState**  
-Stores and retrieves state from `localStorage` to persist data across page reloads.
-
-```ts
-const [theme, setTheme] = usePersistedState('theme', 'light');
-```
----
-  📌 **useHistory**  
- Provides methods to navigate the browser history, including pushing and replacing history states, as well as moving back and forward in the history stack.
-
-```ts
-const {
-  history,
-  state,
-  push,
-  replace,
-  goBack,
-  goForward
-} = useHistory();
-
-push('/about', { from: 'home' });
-replace('/profile');
-goBack();
-goForward();
-```
-
----
-📌 **useRecentSearch**  
- Return and manage recent searched history.
-
-```ts
-  const { recentSearches, addSearch, clearSearch, hasSearch } = useRecentSearch<SearchItem>({
-    key: 'myRecentItems',
-    limit: 5,
-    uniqueKey: 'id',
-    excludeEmpty: true,
-  });
-
-```
----
-📌 **useHistoryState**  
- Manages state history with undo/redo capabilities.
-
-```ts
-const { state, setState, undo, redo } = useHistoryState(initialState);
-
-// Example
-setState({...});
-undo(); // Reverts change
-```
----
-  📌 **useVisibilityChange**  
-Tracks the visibility state of the document and returns whether the page is currently visible or hidden.
-
-```ts
-const isVisible = useVisibilityChange(); // ➝ true | false
-```
----
-📌 **useDarkMode**  
-Detects and manages dark mode preferences in the browser.
-
-```ts
-const [isDarkMode, toggleDarkMode] = useDarkMode();
-```
----
-📌 **usePreferredLanguage**  
-Detects the preferred language set in the browser.
-
-```ts
-const language = usePreferredLanguage();
-```
----
-📌 **useIndexedDB**  
-Provides a hook to interact with IndexedDB in the browser, enabling persistent client-side storage.
-
-```ts
-const { data, setData } = useIndexedDB('dbName');
-```
----
-
-📌 **useMediaQuery**  
-Checks if a media query condition matches the current viewport, useful for responsive design.
-
-```ts
-const isMobile = useMediaQuery('(max-width: 768px)');
-```
----
-📌 **useWindowSize**  
-Returns the current window size (width and height).
-
-```ts
-const { width, height } = useWindowSize();
-```
----
-  📌 **useResizeObserver**  
-Observes and returns the dimensions of an HTML element using the `ResizeObserver` API.
-
-```ts
-const size = useResizeObserver(ref);
-
-// size = { width: 200, height: 100 }
-```
----
-  📌 **useScrollPosition**  
-Tracks the horizontal (x) and vertical (y) scroll positions of the window.
-
-```ts
-const { x, y } = useScrollPosition();
-```
----
-  📌 **useScrollDirection**  
-Determines whether the user is scrolling up or down based on window scroll position changes.
-
-```ts
-const direction = useScrollDirection(); // ➝ 'up' | 'down'
-```
-
-📌 **useScrollLock**  
-Locks or unlocks scrolling on the page.
-
-```ts
-useScrollLock(true); // Lock scrolling
-useScrollLock(false); // Unlock scrolling
-```
----
-📌 **useLockBodyScroll**  
-Prevents scrolling on the body element, useful for modals or off-canvas menus.
-
-```ts
-useLockBodyScroll(true);
-```
----
-📌 **useCss**  
-Allows injecting dynamic CSS rules into the document.
-
-```ts
-useCss('.class { color: red; }');
-```
----
-📌 **useReducedMotion**  
-Detects whether the user has reduced motion settings in their OS preferences.
-
-```ts
-const prefersReducedMotion = useReducedMotion();
-```
----
-📌 **useImageLoader**  
-Provides a way to load and display images in a way that improves performance and loading behavior.
-
-```ts
-const { isLoading, image } = useImageLoader('imageURL');
-```
-
----
-
-  📌 **useBattery**  
- Monitors the battery status of the device, including level, charging status, and remaining charging or discharging time.
-
-```ts
-const { level, charging, supported, loading, chargingTime, dischargingTime } = useBattery();
-```
----
-  📌 **useGeoLocation**  
-Retrieves the user's current geographic location and returns it along with any error encountered.
-
-```ts
-const { position, error } = useGeoLocation();
-```
----
-  📌 **useMousePosition**  
-Tracks the user's mouse position in real-time and returns the coordinates. 
-
-```ts
-const { x, y } = useMousePosition();
-```
-
----
-  📌 **useOnlineStatus**  
-Monitors the user's network connection status (online/offline).
-
-```ts
-const isOnline = useOnlineStatus();
-```
-
----
-
-  📌 **useSound**  
-Controls the playback of an audio file, including play, pause, and stop functionalities, while also managing the audio volume and handling any errors.
-
-```ts
-const {
-  play,
-  pause,
-  stop,
-  setVolume,
-  isPlaying,
-  error
-} = useSound("/sound.mp3");
-
-play();
-pause();
-stop();
-setVolume(0.5);
-```
----
-  📌 **useSpeak**  
-Converts text to speech using the Web Speech API, allowing the text to be spoken and handling errors.
-```ts
-const { speak, error } = useSpeak('Hello world!');
-speak();
-```
----
-
-### 📌 **usePermission**  
-Monitors the status of a specific browser permission (like geolocation, camera, microphone, etc.) and updates reactively when the permission state changes.
-
-```ts
-const permission = usePermission({ name: 'geolocation' });
-```
-
----
-
-### 📌 **usePageLeave**  
-Detects when the mouse leaves the viewport (commonly used to detect exit intent on websites).
-
-```ts
-usePageLeave(() => {
-  console.log('Mouse left the page');
-});
-```
-
----
-
-### 📌 **useMotion**  
-Subscribes to device motion events (like `acceleration` or `rotation`) and returns the latest motion values from sensors on mobile devices.
-
-```ts
-const motion = useMotion();
-console.log(motion.acceleration);
-```
-
----
-
-### 📌 **useHoverDirty**  
-Returns `true` when the mouse is hovering over a target element. Unlike `useHover`, this doesn't handle delays or complex state logic—just raw hover state.
-
-```ts
-const ref = useRef(null);
-const isHovered = useHoverDirty(ref);
-```
-
----
-
-### 📌 **useBeforeUnload**  
-Prompts the user with a confirmation dialog before leaving the page (refresh, close tab, etc.).
-
-```ts
-useBeforeUnload(true); // Triggers default browser dialog
-```
-
----
-
-### 📌 **useClickAway**  
-Triggers a handler function when a user clicks outside of a specified element.
-
-```ts
-const ref = useRef(null);
-useClickAway(ref, () => {
-  console.log('Clicked outside');
-});
-```
-
----
-
-### 📌 **useResponsive**  
-Tracks screen size and returns breakpoint-based flags (`xs`, `sm`, `md`, etc.) to help in building responsive UI layouts.
-
-```ts
-const screens = useResponsive();
-console.log(screens.md); // true or false
-```
-
----
-
-### 📌 **useUnmountedRef**  
-Returns a `ref` that indicates whether the component is currently unmounted—useful to prevent state updates on unmounted components.
-
-```ts
-const unmountedRef = useUnmountedRef();
-```
----
-  📌 **useCountUp**  
- Animates a counter that counts up from 0 to a target value within a specified duration, returning the current count and any errors.
-
-```ts
-const { count, error } = useCountUp(100, 5000); // counts up to 100 in 5s
-```
-
----
-  📌 **useCountDown**  
-Counts down from a specified start value to zero, updating every second and returning the current count and any errors.
-
-```ts
-const { count, error } = useCountDown(10); // counts down from 10
-```
-
----
-
-📌 **useWebSocket**  
- Manages WebSocket connections with auto-reconnect.
-
-```ts
-const { send, message, status } = useWebSocket('ws://api.example.com');
-
-// Example
-send(JSON.stringify({ action: 'ping' }));
-```
-
----
-
-  **License** 
-
-[MIT](https://docs.npmjs.com/policies/npm-license) © (2022-2024)
+
+**react-hook-toolkit** package offers a comprehensive set of hooks to simplify React development. It includes hooks for managing state, handling API requests, optimizing performance, and improving user interactions. Key features include data fetching, form handling, local storage management, debouncing/throttling, window size tracking, event listeners, and more. These hooks are designed to enhance productivity by providing reusable, easy-to-use solutions for common tasks.
+
+**Note : This lightweight and type-safe package is written in TypeScript and offers full support for all hooks across all modern browsers.**
+
+### Installation
+
+Install the package:
+
+```bash
+npm install react-hook-toolkit
+# or
+pnpm add react-hook-toolkit
+```
+
+### **Authors**
+
+![NPM](https://img.shields.io/badge/Author-React_Developers-red) &nbsp; ![npm](https://img.shields.io/npm/v/react-hook-toolkit?color=1C939D) &nbsp; ![npm](https://img.shields.io/npm/dt/react-hook-toolkit) &nbsp; ![NPM](https://img.shields.io/npm/l/react-hook-toolkit) &nbsp; ![NPM Unpacked Size](https://img.shields.io/npm/unpacked-size/react-hook-toolkit)
+
+### **Browser Support**
+
+| ![Firefox](https://raw.githubusercontent.com/alrra/browser-logos/main/src/firefox/firefox_48x48.png) | ![Chrome](https://raw.githubusercontent.com/alrra/browser-logos/main/src/chrome/chrome_48x48.png)  | ![Safari](https://raw.githubusercontent.com/alrra/browser-logos/main/src/safari/safari_48x48.png) | ![Opera](https://raw.githubusercontent.com/alrra/browser-logos/main/src/opera/opera_48x48.png) | ![Edge](https://raw.githubusercontent.com/alrra/browser-logos/main/src/edge/edge_48x48.png)
+| ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| Latest ✔                                                                                          | Latest ✔                                                                                             | Latest ✔                                                                                          | Latest ✔                                                                                       | Latest ✔                                                                                    |
+
+
+### **Documentation**
+
+Comprehensive documentation with step-by-step guides, practical examples, and easy-to-follow explanations to help you quickly understand and use all custom hooks effectively.
+
+👉 https://react-hook-toolkit.netlify.app
+
+
+---
+
+## Available Hooks
+
+### 🔄 State & Data Management
+
+| Hook | Description |
+|------|-------------|
+| `useToggle` | Boolean toggle with a stable flip function |
+| `useBoolean` | Boolean with explicit `setTrue` / `setFalse` / `toggle` / `set` |
+| `usePrevious` | Returns the value from the previous render |
+| `useArray` | Array state with push, removeByIndex, clear helpers |
+| `useList` | Array state with rich set/push/removeAt/insertAt/updateAt/clear actions |
+| `useCounter` | Numeric counter with min/max/step bounds and increment/decrement/reset/set |
+| `useMap` | Map data structure as React state with get/set/delete/clear |
+| `useSet` | Set data structure as React state with add/delete/toggle/clear |
+| `useQueue` | FIFO queue with enqueue/dequeue/peek/clear |
+| `useStack` | LIFO stack with push/pop/peek/clear |
+| `useUndo` | Simple undo/redo state stack |
+| `useHistoryState` | Full undo/redo history with past, present, and future arrays |
+| `useHistory` | push/replace/goBack/goForward wrappers around the History API |
+| `useStateWithCallback` | setState that fires a callback after the update is applied |
+| `useMergeState` | Object state with partial merge (like class component setState) |
+| `useResetState` | useState augmented with a reset() that restores the initial value |
+| `useSyncedState` | State synced across browser tabs/windows via BroadcastChannel |
+| `useDerivedState` | Memoized value computed from a source with explicit transform |
+| `usePatch` | Object state with a patch() method for one-level deep partial updates |
+| `usePersistedState` | useState synced to localStorage |
+| `useSafeState` | Suppresses state updates after component unmount |
+| `useRafState` | Batches state updates via requestAnimationFrame |
+| `useForceUpdate` | Returns a function that forces a component re-render |
+| `useGenericReducer` | Factory for creating typed reducers |
+
+### 🌐 Fetching & API
+
+| Hook | Description |
+|------|-------------|
+| `useAsync` | Runs an async function on mount, tracks status/value/error |
+| `useAsyncCallback` | Imperative async wrapper — isPending/data/error/reset; does not auto-run |
+| `useRequest` | Fetches JSON from a URL, returns `{ data, loading, error }` |
+| `useRequestRetry` | Like `useRequest` with automatic retry on failure |
+| `useAbortFetch` | Fetch with AbortController — auto-cancels on unmount or URL change |
+| `useLazyFetch` | Fetch triggered manually (not on mount) |
+| `usePolling` | Repeatedly calls an async fetcher on a fixed interval |
+| `useOptimisticUpdate` | Applies an optimistic value immediately, rolls back on error |
+| `useInfiniteScroll` | Loads paginated data as the user scrolls to the bottom |
+| `useWebSocket` | Connects to a WebSocket and exposes data/send/isConnected |
+
+### ⏱ Timing & Async
+
+| Hook | Description |
+|------|-------------|
+| `useDebounce` | Debounced copy of a value |
+| `useDebouncedValue` | Alias for `useDebounce` |
+| `useDebouncedCallback` | Debounced callback function |
+| `useDebouncedState` | State that only updates after the setter hasn't been called for N ms |
+| `useThrottle` | Throttled copy of a value |
+| `useDelay` | Delays propagation of a value by a fixed time |
+| `useInterval` | Runs a callback on a repeating interval |
+| `useTimeout` | Runs a callback once after a delay |
+| `useTimer` | Countdown timer that decrements every second |
+| `useCountUp` | Animates a number from 0 up to a target |
+| `useCountDown` | Animates a number from a start value down to 0 |
+| `useClock` | Returns a live `Date` updated every N milliseconds |
+| `useStopwatch` | Start/stop/reset/lap elapsed-time stopwatch in milliseconds |
+| `useAnimationFrame` | Calls a callback on every rAF frame; returns start/stop/isRunning |
+| `useIdleCallback` | Schedules a callback with requestIdleCallback (setTimeout fallback) |
+| `useAsyncEffect` | useEffect wrapper that accepts an async function with cancellation guard |
+
+### 💾 Browser Storage
+
+| Hook | Description |
+|------|-------------|
+| `useLocalStorage` | Reads/writes a localStorage key as state |
+| `useSessionStorage` | Reads/writes a sessionStorage key as state |
+| `useCookie` | Reads, writes, and deletes a browser cookie |
+| `useIndexedDB` | Reads all records from an IndexedDB object store |
+| `usePersistedForm` | Form state that auto-saves to localStorage |
+| `usePersistedState` | Generic state synced to localStorage |
+
+### 📐 DOM & Layout
+
+| Hook | Description |
+|------|-------------|
+| `useWindowSize` | Reactive window width and height |
+| `useResizeObserver` | Observes size changes on a ref'd element |
+| `useMeasure` | Full bounding rect of a ref'd element, updates on resize |
+| `useRect` | Reactive bounding DOMRect via ResizeObserver + scroll — returns `[ref, rect]` |
+| `useScrollPosition` | Current page scroll X/Y |
+| `useScrollDirection` | Whether the user is scrolling `'up'` or `'down'` |
+| `useScrollLock` | Locks/unlocks `document.body` overflow |
+| `useLockBodyScroll` | Locks body scroll and compensates for scrollbar width |
+| `useScrollToTop` | Returns `[isVisible, scrollToTop]` — shows button after threshold |
+| `useScrollIntoView` | Returns ref + function that scrolls the element into the viewport |
+| `useScrollThreshold` | Returns true when page (or element) has scrolled past a pixel offset |
+| `useMousePosition` | Current mouse X/Y relative to the viewport |
+| `useIntersectionObserver` | Tracks whether a ref'd element is visible in the viewport |
+| `useInView` | Convenience `[ref, inView]` wrapper over IntersectionObserver; supports `once` |
+| `useMutationObserver` | Observes DOM mutations on a ref'd element |
+| `useGridLayout` | Tracks CSS grid column and row count of a ref'd element |
+| `useVirtualList` | Windowed (virtual) list — only renders visible items |
+| `useFocusTrap` | Traps keyboard Tab focus within a container (for modals/dialogs) |
+| `useEventListener` | Attaches a single event listener to an element or window |
+| `useEventListeners` | Attaches an event listener with a stable handler ref |
+| `useScript` | Dynamically loads an external script and reports its status |
+| `useCss` | Injects a CSS string into the document head |
+| `useImageLoader` | Tracks loaded/error state of an image src |
+| `useTitle` | Reactively sets `document.title`; optionally restores it on unmount |
+| `useFavicon` | Dynamically updates the page favicon href |
+
+### 🎨 UI & Interaction
+
+| Hook | Description |
+|------|-------------|
+| `useDarkMode` | Tracks and toggles dark mode preference |
+| `useTheme` | light/dark/system theme with localStorage persistence and `data-theme` attribute |
+| `useBreakpoint` | Named breakpoint (`xs`/`sm`/`md`/`lg`/`xl`/`2xl`) from window width |
+| `useMediaQuery` | Returns true when a CSS media query matches |
+| `useReducedMotion` | Returns true when the user prefers reduced motion |
+| `useRipple` | Material-style ripple effect — returns ripple entries and onMouseDown handler |
+| `useToast` | Toast notification state manager with auto-dismiss |
+| `useModal` | Modal open/close state with body scroll lock |
+| `useContextMenu` | Right-click context menu position state |
+| `useHover` | Tracks hover via mouseenter/mouseleave, returns `[ref, isHovered]` |
+| `useHoverDirty` | Tracks hover via mouseover/mouseout on a ref'd element |
+| `useFocus` | Tracks focus state of a ref'd element with programmatic focus/blur |
+| `useClickAway` | Calls a handler when a click occurs outside a ref'd element |
+| `useLongPress` | Fires a callback after a sustained press (mouse or touch) |
+| `useTouch` | Tracks touchstart/touchmove/touchend coordinates on an element |
+| `useSwiping` | Detects swipe gestures (left/right/up/down) with directional callbacks |
+| `usePointers` | Handles all pointer events and tracks active pointers by pointerId |
+| `useDragAndDrop` | Container + draggable item props with `onDrop(from, to)` callback |
+| `useDragReorder` | Drag-and-drop list reordering |
+| `useFileDropArea` | File drag-drop + input handling with type/size validation |
+| `useSelection` | Returns currently selected text and its bounding DOMRect |
+
+### ⌨️ Input & Forms
+
+| Hook | Description |
+|------|-------------|
+| `useInput` | Controlled input state with value/onChange/reset and spread-ready `bind` |
+| `useCheckbox` | Controlled checkbox state with toggle and spread-ready `bind` |
+| `useForm` | Basic form values + per-field validation |
+| `useSmartForm` | Form with auto-save to localStorage and dirty tracking |
+| `useFormSubmit` | Wraps an async submit handler with isSubmitting/submitError |
+| `useFormWizard` | Multi-step form wizard with per-step validation |
+| `useFieldArray` | Dynamic field arrays with append/remove/update |
+| `useCrossFieldValidation` | Cross-field validation returning per-field errors |
+| `useValidation` | Standalone field validation with an array of validator functions |
+| `useSearch` | Search query state with filtered results and optional debounce |
+| `useFilter` | Filters an array by a predicate function |
+| `useSort` | Sorts an array by key with direction toggling |
+| `useAutocomplete` | Suggestions list with keyboard navigation (Up/Down/Enter/Escape) |
+
+### 🧭 Navigation & Routing
+
+| Hook | Description |
+|------|-------------|
+| `useRouter` | Minimal client-side router with pathname, searchParams, and navigate |
+| `useNavigationState` | Tracks pathname/search/state from pushState/popstate |
+| `useHistoryState` | Undo/redo state with full history (past/present/future) |
+| `useMenuNavigation` | Flattens nested menu data and handles path-based selection |
+| `useHash` | Reads and writes the URL hash fragment as state |
+| `useQueryParams` | Reads and writes URL search parameters reactively |
+| `useParams` | Extracts named dynamic route parameters from the current URL path |
+| `usePagination` | Client-side pagination: page, pageSize, totalPages, offset, next/prev/goTo |
+
+### 🔐 Auth & Permissions
+
+| Hook | Description |
+|------|-------------|
+| `usePermission` | Queries the Permissions API for a descriptor |
+
+### 📡 Browser & Device
+
+| Hook | Description |
+|------|-------------|
+| `useBattery` | Battery level, charging state, and charge/discharge times |
+| `useGeoLocation` | Current geolocation position |
+| `useOnlineStatus` | Whether the browser is online |
+| `useNetwork` | Network info: effectiveType, downlink, rtt, saveData |
+| `useNetworkState` | Full NetworkInformation API with `since` timestamp |
+| `useOrientation` | Device screen orientation type/angle with isPortrait/isLandscape |
+| `usePreferredLanguage` | Navigator language and languages list |
+| `useIdle` | Detects user inactivity after a configurable timeout |
+| `usePageVisibility` | Returns true when the current browser tab is visible |
+| `useBrowser` | Full browser controls: navigate, reload, fullscreen, clipboard, share, and more |
+| `useFullscreen` | Fullscreen API for a ref'd element with enter/exit/toggle |
+| `useMediaDevices` | getUserMedia access + device enumeration for camera and microphone |
+| `useAudioAnalyser` | Real-time audio frequency and time-domain data via AnalyserNode |
+| `useScreenCapture` | Screen/window/tab capture via getDisplayMedia |
+| `useGamepad` | Polls Gamepad API state on every rAF frame |
+| `useNotification` | Web Notifications API — request permission and show notifications |
+| `useVibration` | Vibration API — trigger device vibration with a pattern |
+| `useWakeLock` | Screen Wake Lock API — prevents screen from sleeping |
+| `useShareSheet` | Web Share API — triggers the native OS share sheet |
+| `useMotion` | Device motion sensor (acceleration, rotation rate) |
+| `useWorker` | Runs a function in a Web Worker background thread |
+
+### 🗣 Speech & Audio
+
+| Hook | Description |
+|------|-------------|
+| `useSpeech` | Text-to-speech via the SpeechSynthesis API (declarative) |
+| `useSpeak` | Text-to-speech with imperative speak/stop/pause/resume controls |
+| `useVoice` | Speech recognition with command matching, history, wake word, and shortcuts |
+| `useSound` | HTML audio player with play/pause/stop/setVolume controls |
+
+### 🔁 Lifecycle & Utilities
+
+| Hook | Description |
+|------|-------------|
+| `useIsMounted` | Returns true after the component mounts |
+| `useIsFirstRender` | Returns true only on the very first render |
+| `useUnmountedRef` | Ref that becomes true after the component unmounts |
+| `useUpdateEffect` | Like useEffect but skips the first (mount) run |
+| `useIsomorphicEffect` | useLayoutEffect on the browser, useEffect on the server (SSR-safe) |
+| `useBeforeUnload` | Prompts the user before leaving the page |
+| `usePageLeave` | Fires a callback when the mouse leaves the page |
+| `useVisibilityChange` | Returns true when the browser tab is visible |
+| `useLatest` | Ref that always holds the most recent value — avoids stale closures |
+| `useEventCallback` | Stable callback ref — safe for event listeners without re-subscribing |
+| `useStableCallback` | Semantic alias for useEventCallback |
+| `useConstant` | Evaluates an initializer once and never recomputes it |
+| `useComputed` | Memoized derived value — semantic alias for useMemo |
+| `useDeepCompareEffect` | useEffect with deep equality dep comparison |
+| `useDeepCompareMemo` | useMemo with deep equality dep comparison |
+| `useShallowEqual` | Returns the previous (stable) reference when value is shallowly equal |
+| `useStepper` | Step wizard with next/back/reset/goto and isFirstStep/isLastStep |
+| `useRecentSearch` | Persists and manages a recent-searches list in localStorage |
+| `useEventEmitter` | In-component pub/sub: on/off/emit/once/clear |
+| `useClipboard` | Copy text to the clipboard with a copied state |
+| `useScrollIntoView` | Returns ref + scrollIntoView() function |
+
+### 🛠 Context & Optimization
+
+| Hook | Description |
+|------|-------------|
+| `createOptimizedContext` | Creates a context with a selector-based hook to avoid unnecessary re-renders |
+| `useDrawer` | Consumes the DrawerContext (open/close/state) |
+
+### 🐛 Developer Tools
+
+| Hook | Description |
+|------|-------------|
+| `useWhyDidYouUpdate` | Logs which props/state changed to trigger the last render (dev only) |
+| `useLogger` | Logs a label and values on every render (dev only) |
+| `useRenderCount` | Returns the number of times the component has rendered |
+| `useErrorBoundary` | Imperative showBoundary(error) to surface errors to the nearest ErrorBoundary |
+| `useReducerLogger` | Wraps useReducer to log every action and state change (dev only) |
+
+---
+
+  **License**
+
+[MIT](https://docs.npmjs.com/policies/npm-license) © (2022-2024)