tanbal-hooks 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tanbal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,348 @@
+# tanbal-hooks
+
+A collection of useful and reusable React and Next.js hooks.
+
+## Installation
+
+```bash
+npm install tanbal-hooks
+```
+
+## Hooks
+
+* [`useDataManager`](#usedatamanager)
+* [`useLocalStorage`](#uselocalstorage)
+* [`useClickOutside`](#useclickoutside)
+* [`useInputBlur`](#useinputblur)
+* [`useQueryParams`](#usequeryparams)
+
+---
+
+## useDataManager
+
+A hook for managing data through REST API requests.
+
+### Usage
+
+```jsx
+import useDataManager from 'tanbal-hooks';
+
+const [data, status, actions] = useDataManager('/api/users');
+```
+
+### Return value
+
+```js
+[data, status, actions]
+```
+
+`status` can be:
+
+```text
+idle
+loading
+loaded
+failed
+```
+
+`actions` contains:
+
+```js
+{
+    load,
+    add,
+    update,
+    updateMultiple,
+    remove,
+    get,
+}
+```
+
+### Methods
+
+#### `load(successCallback, failCallback, finallyCallback)`
+
+Loads data using `GET`.
+
+```js
+await actions.load(
+    data => console.log(data),
+    error => console.error(error),
+    () => console.log('finished')
+);
+```
+
+#### `add(data, successCallback, failCallback, finallyCallback)`
+
+Adds a new item using `POST`.
+
+```js
+await actions.add({
+    name: 'Ali',
+});
+```
+
+#### `update(id, newData, successCallback, failCallback, finallyCallback)`
+
+Updates an item using `PATCH`.
+
+```js
+await actions.update(1, {
+    name: 'Ali Reza',
+});
+```
+
+#### `updateMultiple(updates, successCallback, failCallback, finallyCallback)`
+
+Updates multiple items using `PATCH`.
+
+```js
+await actions.updateMultiple([
+    { id: 1, name: 'Ali' },
+    { id: 2, name: 'Reza' },
+]);
+```
+
+#### `remove(id, successCallback, failCallback, finallyCallback)`
+
+Removes an item using `DELETE`.
+
+```js
+await actions.remove(1);
+```
+
+#### `get(which, key = 'id')`
+
+Finds an item by a specified key.
+
+```js
+const user = actions.get(1);
+
+const user = actions.get('Ali', 'name');
+```
+
+---
+
+## useLocalStorage
+
+A hook for storing and synchronizing a value with `localStorage`.
+
+### Usage
+
+```jsx
+import useLocalStorage from 'tanbal-react-hooks';
+
+const [value, setValue] = useLocalStorage('theme', 'light');
+```
+
+The hook returns:
+
+```js
+[value, setValue]
+```
+
+The stored value is automatically read from `localStorage` when the key changes and saved whenever the value changes.
+
+---
+
+## useClickOutside
+
+A hook for detecting clicks outside of an element.
+
+### Usage
+
+```jsx
+import useClickOutside from 'tanbal-react-hooks';
+
+const ref = useClickOutside(() => {
+    console.log('Clicked outside');
+}, true);
+
+return (
+    <div ref={ref}>
+        Content
+    </div>
+);
+```
+
+### Parameters
+
+```js
+useClickOutside(onOutsideClick, isActive)
+```
+
+* `onOutsideClick` — callback called when a click occurs outside the referenced element.
+* `isActive` — enables or disables the listener. Defaults to `false`.
+
+---
+
+## useInputBlur
+
+A hook for handling input events with a delay and executing a callback when the input loses focus.
+
+### Usage
+
+```jsx
+import useInputBlur from 'tanbal-react-hooks';
+
+const inputRef = useInputBlur(500, value => {
+    console.log(value);
+});
+
+return <input ref={inputRef} />;
+```
+
+### Parameters
+
+```js
+useInputBlur(time, callback)
+```
+
+* `time` — delay in milliseconds before the callback is executed after input.
+* `callback` — callback receiving the current input value.
+
+The callback is also executed immediately when the input loses focus.
+
+---
+
+## useQueryParams
+
+A Next.js hook for managing URL query parameters and synchronizing them with React state.
+
+> This hook uses `next/navigation` and is intended for Next.js App Router applications.
+
+### Usage
+
+```jsx
+import useQueryParams from 'tanbal-react-hooks';
+
+const [query, state, setState] = useQueryParams(
+    {
+        search: '',
+    },
+    {
+        search: {
+            path: 'search',
+        },
+    }
+);
+```
+
+The hook returns:
+
+```js
+[actions, state, setState]
+```
+
+### Actions
+
+```js
+{
+    get,
+    set,
+    setMultiple,
+    remove,
+    removeParams,
+    reset,
+    getPath,
+}
+```
+
+### `get(key)`
+
+Gets a query parameter.
+
+```js
+const value = query.get('search');
+```
+
+Returns `null` when the parameter is empty or does not exist.
+
+### `set(key, value, replace = true)`
+
+Sets a query parameter and updates the corresponding state value.
+
+```js
+query.set('search', 'react');
+```
+
+### `setMultiple(newValues)`
+
+Sets multiple query parameters at once.
+
+```js
+query.setMultiple({
+    search: 'react',
+    page: 2,
+});
+```
+
+### `remove(key, replace = true)`
+
+Removes a query parameter and clears its corresponding state value.
+
+```js
+query.remove('search');
+```
+
+### `removeParams(paramsList)`
+
+Removes multiple query parameters.
+
+```js
+query.removeParams(['search', 'page']);
+```
+
+### `reset()`
+
+Removes all configured query parameters.
+
+```js
+query.reset();
+```
+
+### `getPath(key)`
+
+Returns the configured state path for a query parameter.
+
+```js
+const path = query.getPath('search');
+```
+
+### Configuration
+
+Each query parameter can be configured with:
+
+```js
+{
+    search: {
+        path: 'filters.search',
+        emptyValues: [''],
+        inputTransform: value => value,
+        paramsTransform: value => value,
+    },
+}
+```
+
+* `path` — path used to store the parameter in the state.
+* `emptyValues` — values treated as empty.
+* `inputTransform` — transforms values before storing them in the state or URL.
+* `paramsTransform` — transforms values read from the URL before storing them in the state.
+
+### Options
+
+The third argument can be used to configure initial parameter synchronization:
+
+```js
+useQueryParams(initialState, keys, {
+    syncInitialParams: true,
+});
+```
+
+`syncInitialParams` defaults to `true`.
+
+---
+
+## License
+
+MIT

package/data-manager/useDataManager.js

@@ -0,0 +1,157 @@
+import { useState } from "react";
+import Fetch from 'tanbal-utils';
+
+const useDataManager = (url) => {
+    const [data, setData] = useState([]);
+    const [status, setStatus] = useState('idle');
+
+    const load = async (
+        successCallback = () => {},
+        failCallback = () => {},
+        finallyCallback = () => {},
+    ) => {
+        try {
+            setStatus('loading');
+            const result = await Fetch(url);
+            setData(result.data);
+            setStatus('loaded');
+            successCallback(result.data);
+        }
+        catch (error) {
+            setStatus('failed');
+            failCallback(error);
+            throw error;
+        }
+        finally {
+            finallyCallback();
+        }
+    }
+
+    const add = async (
+        data,
+        successCallback = () => {},
+        failCallback = () => {},
+        finallyCallback = () => {},
+    ) => {
+        try {
+            const result = await Fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify(data),
+            });
+            load();
+            successCallback(result);
+            return result;
+        }
+        catch (error) {
+            failCallback(error);
+            throw error;
+        }
+        finally {
+            finallyCallback();
+        }
+    }
+
+    const update = async (
+        id,
+        newData,
+        successCallback = () => {},
+        failCallback = () => {},
+        finallyCallback = () => {},
+    ) => {
+
+        try {
+            const result = await Fetch(`${url}/${id}`, {
+                method: 'PATCH',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify(newData),
+            });
+            load();
+            successCallback(result);
+            return result;
+        }
+        catch (error) {
+            failCallback(error);
+            throw error;
+        }
+        finally {
+            finallyCallback();
+        }
+    }
+
+    const updateMultiple = async (
+        updates,
+        successCallback = () => {},
+        failCallback = () => {},
+        finallyCallback = () => {},
+    ) => {
+        try {
+            const result = await Fetch(url, {
+                method: 'PATCH',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify(updates),
+            });
+            load();
+            successCallback(result);
+            return result;
+        }
+        catch (error) {
+            failCallback(error);
+            throw error;
+        }
+        finally {
+            finallyCallback();
+        }
+    }
+
+    const remove = async (
+        id,
+        successCallback = () => {},
+        failCallback = () => {},
+        finallyCallback = () => {},
+    ) => {
+        try {
+            const result = await Fetch(`${url}/${id}`, {
+                method: 'DELETE',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify(id),
+            });
+            load();
+            successCallback(result);
+            return result;
+        }
+        catch (error) {
+            failCallback(error);
+            throw error;
+        }
+        finally {
+            finallyCallback();
+        }
+    }
+
+    const get = (
+        which,
+        key = 'id',
+    ) => {
+        return data.find(item => item[key] === which);
+    }
+
+    return [data, status, {
+        load,
+        add,
+        update,
+        updateMultiple,
+        remove,
+        get,
+    }];
+}
+
+export default useDataManager;

package/data-manager/useLocalStorage.js

@@ -0,0 +1,31 @@
+import { useEffect, useState } from "react";
+
+function useLocalStorage(key, initialValue) {
+
+  const [value, setValue] = useState(initialValue);
+  const [initialized, setInitialized] = useState(false);
+
+  useEffect(() => {
+    try {
+      const item = localStorage.getItem(key);
+      if (item !== null) {
+        setValue(JSON.parse(item));
+      }
+    }
+    catch {
+      // use initialValue
+    }
+    finally {
+      setInitialized(true);
+    }
+  }, [key]);
+
+  useEffect(() => {
+    if (!initialized) return;
+    localStorage.setItem(key, JSON.stringify(value));
+  }, [key, value, initialized]);
+
+  return [value, setValue];
+}
+
+export default useLocalStorage;

package/event/useClickOutside.js

@@ -0,0 +1,24 @@
+import { useEffect, useRef } from "react"
+
+const useClickOutside = (
+    onOutsideClick,
+    isActive = false
+) => {
+    const ref = useRef(null);
+
+    useEffect(() => {
+        if (!isActive) return;
+        const handleClick = event => {
+            if (ref?.current && !ref.current.contains(event.target)) {
+                onOutsideClick()
+            }
+        }
+
+        document.addEventListener('mousedown', handleClick)
+        return () => document.removeEventListener('mousedown', handleClick)
+    }, [ref, onOutsideClick, isActive]);
+
+    return ref;
+}
+
+export default useClickOutside;

package/event/useInputBlur.js

@@ -0,0 +1,45 @@
+import { useRef } from "react";
+
+const useInputBlur = (
+    time,
+    callback = () => {}
+) => {
+    const ref = useRef(null);
+    const timer = useRef(null);
+    const callbackRef = useRef(callback);
+
+    useEffect(() => {
+        const input = ref?.current;
+        if (!input) return;
+        const handleInput = () => {
+            clearTimeout(timer.current);
+
+            timer.current = setTimeout(() => {
+                callbackRef.current(input.value);
+            }, time);
+        };
+
+        const handleBlur = () => {
+            clearTimeout(timer.current);
+            callbackRef.current(input.value);
+        };
+
+        input.addEventListener('input', handleInput);
+        input.addEventListener('blur', handleBlur);
+
+        return () => {
+            input.removeEventListener('input', handleInput);
+            input.removeEventListener('blur', handleBlur);
+            clearTimeout(timer.current);
+        };
+    }, [ref, time]);
+
+
+    useEffect(() => {
+        callbackRef.current = callback;
+    }, [callback]);
+
+    return ref;
+}
+
+export default useInputBlur;

package/index.js

@@ -0,0 +1,13 @@
+import useDataManager from "./data-manager/useDataManager";
+import useLocalStorage from "./data-manager/useLocalStorage";
+import useClickOutside from "./event/useClickOutside";
+import useInputBlur from "./event/useInputBlur";
+import useQueryParams from './useQueryParams';
+
+export {
+    useDataManager,
+    useLocalStorage,
+    useClickOutside,
+    useInputBlur,
+    useQueryParams,
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "tanbal-hooks",
+  "version": "1.0.0",
+  "description": "A collection of custom React and Next.js hooks.",
+  "keywords": [
+    "react",
+    "hooks",
+    "react-hooks",
+    "custom-hooks",
+    "nextjs"
+  ],
+  "homepage": "https://github.com/tanbal8/hooks#readme",
+  "bugs": {
+    "url": "https://github.com/tanbal8/hooks/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tanbal8/hooks.git"
+  },
+  "license": "MIT",
+  "author": "Ali Radmard",
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "peerDependencies": {
+    "next": ">=13",
+    "react": ">=18"
+  },
+  "dependencies": {
+    "tanbal-utils": "^1.0.0"
+  }
+}

package/useQueryParams.js

@@ -0,0 +1,188 @@
+import { useSearchParams, useRouter } from "next/navigation";
+import { useEffect, useState } from "react";
+import { set as setObject, get as getObject } from 'tanbal-utils';
+
+const useQueryParams = (initialState = {}, keys = {}, options = {}) => {
+    const searchParams = useSearchParams();
+    const router = useRouter();
+    const [state, setState] = useState(initialState);
+    const { syncInitialParams = true } = options;
+    
+    const isEmpty = (value, key) => {
+        const emptyValues = getEmptyValues(key);
+        return !value || emptyValues.includes(value);
+    }
+    
+    const getPath = (key) => {
+        return keys?.[key]?.['path'];
+    }
+    
+    const getEmptyValues = (key) => {
+        return keys?.[key]?.emptyValues || [''];
+    }
+    
+    const inputTransform = (key, value) => {
+        const callback = keys?.[key]?.inputTransform || (value => value);
+        return callback(value);
+    }
+
+    const  paramsTransform = (key, value) => {
+        const callback = keys?.[key]?.paramsTransform || (value => value);
+        return callback(value);
+    }
+
+    const replaceParams = (params) => {
+        router.replace(`?${params.toString()}`, { scroll: false });
+    }
+
+    const validateKey = key => {
+        if (!Object.hasOwn(keys, key)) {
+            throw new Error(`Invalid query param key: ${key}`);
+        }
+    };
+
+    const forEachKey = (
+        keys,
+        path = value => value,
+        notEmptyCallback = () => {},
+        emptyCallback = () => {},
+    ) => {
+        Object.entries(keys).forEach(([key, config]) => {
+            const newValue = inputTransform(key, path(config));
+            const empty = isEmpty(newValue, key);
+            if (empty) emptyCallback(key, newValue);
+            else notEmptyCallback(key, newValue);
+        });
+    };
+    
+    const get = (key) => {
+        validateKey(key);
+        const value = searchParams.get(key);
+        if (isEmpty(value, key)) return null;
+        return value;
+    }
+
+    const getStateFromParams = (prevState) => {
+        let newState = { ...prevState };
+        Object.keys(keys).forEach(key => {
+            const value = get(key);
+            if (value !== null) {
+                newState = setObject(
+                    newState,
+                    getPath(key),
+                    paramsTransform(key, value),
+                );
+            }
+        });
+        return newState;
+    };
+    
+    const removeParam = key => {
+        const params = new URLSearchParams(searchParams);
+        params.delete(key);
+        replaceParams(params);
+    };
+
+
+    const setParam = (key, value) => {
+        const params = new URLSearchParams(searchParams);
+        params.set(key, value);
+        replaceParams(params);
+    };
+
+    const remove = (key, replace = true) => {
+        validateKey(key);
+        setState(prevState =>
+            setObject(prevState, getPath(key), '')
+        );
+        if (replace) removeParam(key);
+    };
+    
+    const set = (key, value, replace = true) => {
+        validateKey(key);
+        const newValue = inputTransform(key, value);
+        if (isEmpty(newValue, key)) {
+            remove(key, replace);
+            return;
+        }
+        setState(prevState =>
+            setObject(prevState, getPath(key), newValue)
+        );
+        if (replace) setParam(key, newValue);
+    };
+
+    const setMultiple = (newValues) => {
+        const params = new URLSearchParams(searchParams);
+        forEachKey(
+            newValues,
+            value => value,
+            (key, value) => params.set(key, value),
+            key => params.delete(key),
+        );
+        setState(prevState => {
+            let newState = prevState;
+            forEachKey(
+                newValues,
+                value => value,
+                (key, value) => {
+                    newState = setObject(newState, getPath(key), value);
+                },
+                key => {
+                    newState = setObject(newState, getPath(key), '');
+                },
+            );
+            return newState;
+        });
+        replaceParams(params);
+    };
+    
+    const removeParams = (paramsList = []) => {
+        const params = new URLSearchParams(searchParams);
+        paramsList.forEach(key => {
+            params.delete(key);
+        });
+        setState(prevState => {
+            let newState = prevState;
+            paramsList.forEach(key => {
+                newState = setObject(newState, getPath(key), '');
+            });
+            return newState;
+        });
+        replaceParams(params);
+    };
+
+    const reset = () => {
+        removeParams(Object.keys(keys));
+    }
+
+    useEffect(() => {
+        setState(prevState => getStateFromParams(prevState));
+    }, [searchParams]);
+
+    useEffect(() => {
+        if (!syncInitialParams) return;
+        const params = new URLSearchParams(searchParams);
+        forEachKey(
+            keys,
+            config => getObject(initialState, config.path),
+            (key, value) => {
+                if (!params.has(key)) {
+                    params.set(key, value);
+                }
+            },
+        );
+        replaceParams(params);
+    }, []);
+
+    return [{
+        get,
+        set,
+        setMultiple,
+        remove,
+        removeParams,
+        reset,
+        getPath,
+    }, state, setState];
+}
+
+export default useQueryParams;