@bigbinary/neeto-commons-frontend 2.1.5 → 2.1.7

package/react-utils.d.ts

@@ -6,7 +6,9 @@ import { StoreApi, UseBoundStore } from "zustand";
 import { UseQueryOptions, UseQueryResult, UseMutationOptions, UseMutationResult } from "react-query";
 /**
  *
- * ErrorBoundary which reports frontend errors to HoneyBadger
+ * The HoneybadgerErrorBoundary is an ErrorBoundary which reports frontend errors
+ *
+ * to HoneyBadger.
  *
  * This component will wrap its children with the error boundary provided by
  *
@@ -53,9 +55,9 @@ export const HoneybadgerErrorBoundary: React.FC<{
 }>;
 /**
  *
- * A route that will restrict access to it based on a specified condition and
+ * PrivateRoute is a route that will restrict access to it based on a specified
  *
- * permissions.
+ * condition and permissions.
  *
  * If the given condition is true and the user has the required permissions, it
  *
@@ -89,14 +91,22 @@ type OptionsType = {
 };
 /**
  *
- * This hook allows you to detect when a target element intersects with an ancestor
+ * The useIsElementVisibleInDom hook is a utility that allows you to determine
+ *
+ * whether a target element is currently visible within the viewport or intersects
+ *
+ * with an ancestor element. In simpler terms, it helps you know when a specified
+ *
+ * element is scrolled out of or scrolled into the screen's visible area.
  *
- * element. In simple words, it lets us know whether the target element is visible
+ * The following code snippet demonstrates the usage of useIsElementVisibleInDom
  *
- * on the screen.
+ * to display the heading element.
  *
  * @example 
  *
+ * import { useIsElementVisibleInDom } from "@bigbinary/neeto-commons-frontend/react-utils";
+ * 
  * const ref = useRef(null);
  * const isHeadingWrapperVisible = useIsElementVisibleInDom(ref.current, {
  *   threshold: 0.5,
@@ -113,22 +123,36 @@ type OptionsType = {
  *   </div>
  * );
  * @endexample
+ * The hook watches for changes in the visibility of the referenced div element
+ *
+ * and provides a boolean value that you can use to conditionally render the header
+ *
+ * element with the text Hello I'm on the screen.
+ *
 */
 export function useIsElementVisibleInDom(target: Element | null, options?: OptionsType): Boolean;
 /**
  *
- * Wrap this hook around a frequently updating state to get the previous value
+ * The useDebounce hook is a utility that allows you to wrap around a frequently
  *
- * until the updates are stopped. We can use this to limit the number of API calls
+ * updating state to retrieve the previous value until the updates are halted. This
  *
- * triggered from a user input like search box. The value returned by the hook will
+ * is particularly useful when you want to limit the number of API calls triggered
  *
- * only reflect the latest value when the hook has not been called for the
+ * by user inputs, such as a search box. The value returned by this hook will only
  *
- * specified time period delay.
+ * reflect the latest value when the hook has not been called for the specified
+ *
+ * time period delay.
+ *
+ * The following code snippet demonstrates the usage of useDebounce in a search
+ *
+ * feature.
  *
  * @example 
  *
+ * import { useDebounce } from "@bigbinary/neeto-commons-frontend/react-utils";
+ * 
  * const [searchKey, setSearchKey] = useState("");
  * const debouncedSearchKey = useDebounce(searchKey, 300);
  * 
@@ -140,20 +164,58 @@ export function useIsElementVisibleInDom(target: Element | null, options?: Optio
  * // component
  * <Input onChange={e => setSearchKey(e.target.value)} />;
  * @endexample
+ * In the case of a search box, implemented without debouncing, every keystroke
+ *
+ * typically triggers a search query to find matching results. However, this rapid
+ *
+ * succession of queries can lead to several issues like performance overhead, poor
+ *
+ * user experience and inefficient resource usage.
+ *
+ * The useDebounce hook elegantly solves these problems by delaying the execution
+ *
+ * of the search function until the user pauses typing for a specified duration.
+ *
+ * This ensures that only one API request is made for the entire search operation,
+ *
+ * which solves all the issues mentioned earlier.
+ *
+ * You can learn more about the concept of debouncing
+ *
+ * here.
+ *
 */
 export function useDebounce<T>(value: T, delay?: number): T;
 /**
  *
- * Similar to useDebounce but this hook accepts a function as an argument. That
+ * The useFuncDebounce hook is a utility that extends the benefits of debouncing
+ *
+ * to functions.
+ *
+ * When the debounced function is called, it sets a timer to execute the original
  *
- * function will be executed only when the dependencies stops changing for a while.
+ * function after a specified delay. If the debounced function is called again
  *
- * The debounced function comes with a cancel method which can be used to cancel
+ * before the timer expires, the previous timer is cleared. This effectively delays
  *
- * the delayed function invocation.
+ * the execution of the original function until the debounced function hasn't been
+ *
+ * called for the specified delay period.
+ *
+ * The hook also provides a cancel method to manually cancel the execution of the
+ *
+ * debounced function before it triggers.
+ *
+ * The following code snippet demonstrates the usage of useFuncDebounce in the
+ *
+ * delaying the invocation of the fetch method until the user pauses typing for a
+ *
+ * specific period.
  *
  * @example 
  *
+ * import { useFuncDebounce } from "@bigbinary/neeto-commons-frontend/react-utils";
+ * 
  * const searchForProducts = useFuncDebounce(async key => {
  *   // this function will be triggered once after user stops typing for 300ms
  *   const products = await productsApi.fetch(key);
@@ -170,18 +232,38 @@ export function useFuncDebounce<F extends Function>(func: F, delay?: number): F
 };
 /**
  *
- * This hook can be used to sync state to local storage so that it persists through
+ * The useLocalStorage hook is a utility for synchronizing and persisting state
  *
- * a page refresh.
+ * in the local storage of a web browser. It allows you to maintain data across
  *
- * Note: use this hook only if you need the component to re-render while
+ * page refreshes or even when the user navigates away from the page. This is
+ *
+ * useful for storing user preferences, settings, or any other data that should
+ *
+ * persist between sessions.
+ *
+ * To remove the value from local storage we can call the setter method with null
+ *
+ * or undefined.
+ *
+ * Note: Use this hook only if you need the component to re-render while
  *
  * updating the local storage value. If all you need is plain read and write
  *
  * operations on the localStorage, prefer the vanilla localStorage API functions.
  *
+ * This hook will return an array with exactly two values just like useState
+ *
+ * hook.
+ *
+ * The following code snippet illustrates the usage of useLocalStorage in
+ *
+ * implementing a theme-switching feature.
+ *
  * @example 
  *
+ * import { useLocalStorage } from "@bigbinary/neeto-commons-frontend/react-utils";
+ * 
  * // here "theme" is the storage key and "light" is the initial value
  * const [theme, setTheme] = useLocalStorage("theme", "light");
  * 
@@ -196,82 +278,168 @@ export function useFuncDebounce<F extends Function>(func: F, delay?: number): F
  *   />
  * );
  * @endexample
- * To remove the value from local storage we can call the setter method with null
+ * The initial value is used when the key is not found in local storage, ensuring
  *
- * or undefined.
+ * that a default theme is applied when the user first visits the site. Subsequent
+ *
+ * changes to the theme are automatically synchronized with local storage.
  *
 */
 export function useLocalStorage<T>(key: string, initialValue?: T): [T, (value: T) => void];
 /**
  *
- * A hook used to detect clicks outside of a specified element.
+ * The useOnClickOutside hook is a useful utility for detecting clicks that occur
+ *
+ * outside of a specified element. It provides an elegant way to handle scenarios
+ *
+ * where you want to close or perform specific actions when a user clicks outside
+ *
+ * of a particular component, such as a modal dialog.
+ *
+ * The following code snippet demonstrates the usage of useOnClickOutside to
+ *
+ * detect clicks outside of a dropdown element and conditionally render the
+ *
+ * options.
  *
  * @example 
  *
- * const ref = useRef();
- * const [isModalOpen, setIsModalOpen] = useState(false);
+ * import { useOnClickOutside } from "@bigbinary/neeto-commons-frontend/react-utils";
  * 
- * useOnClickOutside(ref, () => setIsModalOpen(false));
+ * const Dropdown = () => {
+ *   const dropdownRef = useRef(null);
+ *   const [isDropdownOpen, setIsDropdownOpen] = useState(false);
  * 
- * return (
- *   <>
- *     { When we click inside of this modal, it won't close. But when we click outside, it'll close! }
- *     {isModalOpen && (
- *       <div ref={ref}>
- *         <p>Hello from Modal!</p>
- *       </div>
- *     )}
- *     <button onClick={() => setIsModalOpen(true)}>Open Modal</button>
- *   </>
- * );
+ *   // Use the useOnClickOutside hook to close the dropdown when clicking outside of it
+ *   useOnClickOutside(dropdownRef, () => setIsDropdownOpen(false));
+ * 
+ *   return (
+ *     <div className="dropdown" ref={dropdownRef}>
+ *       <button onClick={() => setIsDropdownOpen(!isDropdownOpen)}>
+ *         Toggle Dropdown
+ *       </button>
+ *       {isDropdownOpen && (
+ *         <ul className="dropdown-menu">
+ *           <li>Option 1</li>
+ *           <li>Option 2</li>
+ *           <li>Option 3</li>
+ *         </ul>
+ *       )}
+ *     </div>
+ *   );
+ * };
  * @endexample
 */
 export function useOnClickOutside<T>(ref: React.MutableRefObject<T>, handler: (event: MouseEvent | TouchEvent) => any);
 /**
  *
- * A hook that returns the previous value of a variable before the last update.
+ * The usePrevious hook is a convenient utility to track the previous value of
+ *
+ * its argument before its most recent update. When it is called for the first
+ *
+ * time, it returns the initial value passed as an argument, and subsequently, it
  *
- * In the below example, when count is updated to 10, previousCount will be 0.
+ * returns the previous value every time the component re-renders.
  *
- * If count is again updated to 20, previousCount will be 10.
+ * The hook can be useful in monitoring modifications to form fields, such as
+ *
+ * detecting when fields become dirty, and taking action based on these
+ *
+ * alterations.
+ *
+ * The following code snippet illustrates the usage of usePrevious in tracking
+ *
+ * which fields were modified in a form. By comparing the current and previous
+ *
+ * values of form fields, you can easily identify and handle changes without the
+ *
+ * need for complex state management.
  *
  * @example 
  *
- * const [count, setCount] = useState(0);
- * const previousCount = usePrevious(count);
+ * import { usePrevious } from "@bigbinary/neeto-commons-frontend/react-utils";
+ * 
+ * // Initialize state for a form field (e.g., an input field)
+ * const [name, setName] = useState("");
+ * 
+ * // Use the usePrevious hook to obtain the previous value of name
+ * const previousName = usePrevious(name);
+ * 
+ * // Use useEffect to detect changes in the 'name' field
+ * useEffect(() => {
+ *   // Check if the 'name' field has changed
+ *   if (name !== previousName) {
+ *     // The 'name' field has been modified
+ *     // You can perform actions here, such as marking it as 'dirty'
+ *     // or updating other parts of your application
+ *   }
+ * }, [name]);
  * @endexample
+ * In the example, the useEffect block listens for changes in the name field.
+ *
+ * When the name field is updated, it compares the current value to the previous
+ *
+ * value. If they differ, it signifies that the field has been modified, enabling
+ *
+ * you to take appropriate actions.
+ *
 */
 export function usePrevious<T>(value: T): T;
 /**
  *
- * A hook very similar to useEffect. The only difference is that it will not
+ * The useUpdateEffect hook is a variation of the standard useEffect hook in
+ *
+ * React. The key difference is that useUpdateEffect does not execute the
  *
- * execute the callback in the initial mount. The callback will be triggered only
+ * provided callback during the initial component mount. Instead, it only triggers
  *
- * if the dependencies change.
+ * the callback when the specified dependencies change. This behavior can be
+ *
+ * advantageous when you want to perform actions or side effects in response to
+ *
+ * changes in specific variables after the initial rendering of your component.
+ *
+ * The following code snippet shows the usage of useUpdateEffect in displaying
+ *
+ * category when its value is modified.
  *
  * @example 
  *
+ * import { useUpdateEffect } from "@bigbinary/neeto-commons-frontend/react-utils";
+ * 
+ * // Initialize state variables
+ * const [category, setCategory] = useState("default");
+ * 
+ * // Use useUpdateEffect to update content based on category changes
  * useUpdateEffect(() => {
- *   setTitle(value);
- * }, [value]);
+ *   // This callback will run when 'category' changes, but not during the initial mount
+ *   console.log(`Category has been modified to ${category}`);
+ * }, [category]);
  * @endexample
+ * The useUpdateEffect hook allows you to specify a callback function that will
+ *
+ * only execute when certain dependencies, in this case, the category state,
+ *
+ * change after the initial mount.
+ *
 */
 export function useUpdateEffect(effect: () => void, deps: any[]): void;
 /**
  *
- * This hook will return true if any API request fails with 404 or 403 status.
+ * The useDisplayErrorPage hook is a utility that allows you to conditionally
  *
- * Until any such API response is received, it will return false. It can be used
+ * render an error page in your application based on the status codes of API
  *
- * to render ErrorPage conditionally. Refer:
+ * responses.
  *
- * axios error response handler
+ * The following code snippet demonstrates the usage of useDisplayErrorPage in
  *
- * for more details.
+ * conditionally rendering an error page.
  *
  * @example 
  *
+ * import { useDisplayErrorPage } from "@bigbinary/neeto-commons-frontend/react-utils";
+ * 
  * const App = () => {
  *   const isError = useDisplayErrorPage();
  * 
@@ -286,7 +454,7 @@ export function useUpdateEffect(effect: () => void, deps: any[]): void;
 export function useDisplayErrorPage(): boolean;
 /**
  *
- * A zustand store containing the status code of the latest API failed with 403 or
+ * A Zustand store containing the status code of the latest API failed with 403 or
  *
  * 404 status. It stores the following values:
  *
@@ -309,11 +477,13 @@ type TimerType = {
 };
 /**
  *
- * The useTimer hook re-renders in the specified time interval. This can
+ * The useTimer hook is a utility that enables automatic re-renders of a
  *
- * auto-update the rendered elapsed time in components without requiring the
+ * component at specified time intervals. This functionality is particularly useful
  *
- * application to be manually refreshed.
+ * for updating rendered content, such as elapsed time, without requiring manual
+ *
+ * refreshes.
  *
  * All invocations of useTimer hooks are attached to a single setInterval call
  *
@@ -327,14 +497,23 @@ type TimerType = {
  *
  * second than the scheduled time interval to re-render.
  *
+ * The following demonstrates the usage of useTimer hook in displaying
+ *
+ * time-sensitive information.
+ *
  * @example 
  *
- * import { useTimer } from "neetocommons/react-utils";
+ * import { useTimer } from "@bigbinary/neeto-commons-frontend/react-utils";
+ * 
+ * const Post = () => {
+ *   // Use the useTimer hook with a custom interval
+ *   useTimer(30);
  * 
- * const Component = () => {
- *   useTimer(timerIntervalInSeconds);
+ *   // Calculate the elapsed time since the post creation
+ *   const currentTime = new Date();
+ *   const elapsedTimeInSeconds = Math.floor((currentTime - createdAt) / 1000);
  * 
- *   // Rest of the component
+ *   return <p>Elapsed Time in seconds: {elapsedTimeInSeconds}</p>;
  * };
  * @endexample
 */
@@ -342,9 +521,9 @@ export function useTimer(interval: number): TimerType;
 type ZustandConfigType = (set: (data: any) => void, get: () => any, api: any) => any;
 /**
  *
- * A zustand middleware function that prevents the actions from getting
+ * withImmutableActions is a Zustand middleware function that prevents the
  *
- * overwritten.
+ * actions from getting overwritten.
  *
  * @example 
  *
@@ -358,33 +537,48 @@ type ZustandConfigType = (set: (data: any) => void, get: () => any, api: any) =>
  *   }))
  * );
  * @endexample
- * In the above example, usages like this will throw an error, because, actions
+ * In the example above, any attempts like the following will trigger an error
  *
- * should not be overwritten:
+ * because actions should never be overwritten:
  *
  * @example 
  *
  * setGlobalState({ value: 0, setValue: () => {} });
  * @endexample
- * Actions can be assigned its own value. This is to ensure that curried ramda
+ * However, actions can be assigned their own values. This enables you to use
  *
- * functions can be used in conjunction with zustand action. For example, this
+ * curried Ramda functions in conjunction with Zustand actions. For instance, the
  *
- * usage will not throw any error:
+ * following usage will not result in an error:
  *
  * @example 
  *
  * setGlobalState(state => ({ value: 0, setValue: state.setValue }));
  * @endexample
- * The 2nd parameter to overwrite the entire state will be ignored. Both of the
+ * The second parameter to overwrite the entire state will be ignored. Both of the
  *
- * following lines of code work identical to each other:
+ * following lines of code are functionally equivalent:
  *
  * @example 
  *
  * setGlobalState(state => ({ value: 0 }), true);
  * setGlobalState(state => ({ value: 0 }));
  * @endexample
+ * It should be noted that the withImmutableActions middleware intercepts and
+ *
+ * wraps the set method of the Zustand store to enforce immutability rules.
+ *
+ * Therefore, usages of useStore.setState() won't be handled by the middleware
+ *
+ * since they directly update the state in Zustand without going through the set
+ *
+ * method of the store.
+ *
+ * @example 
+ *
+ * // This won't be handled by the middleware.
+ * useStore.setState({ value: 0, setValue: () => {} });
+ * @endexample
 */
 export function withImmutableActions(config: ZustandConfigType): ZustandConfigType;
 export declare type ZustandStoreHook = UseBoundStore<StoreApi<any>> & {
@@ -392,16 +586,29 @@ export declare type ZustandStoreHook = UseBoundStore<StoreApi<any>> & {
 };
 /**
  *
- * This hook calls onSubmit callback when Enter (aka Return) key is pressed. It
+ * The useFieldSubmit hook simplifies the task of capturing the Enter
+ *
+ * (Return) key press event within an input field and executing a callback
  *
- * will not submit when Shift + Enter is pressed. Shift + Enter can be used to
+ * function when the Enter key is pressed. This is a common requirement in forms
  *
- * add new lines to text area in the form. The hook returns a ref. This need to
+ * where pressing Enter should trigger specific actions, such as submitting a
  *
- * be attached to the input element to be listened to.
+ * form or processing user input. Importantly, this hook ensures that pressing
+ *
+ * Shift + Enter does not trigger the callback, allowing for the creation of
+ *
+ * multi-line text inputs.
+ *
+ * The following code snippet illustrates the usage of useFieldSubmit in building
+ *
+ * an interactive textarea input field.
  *
  * @example 
  *
+ * import { useFieldSubmit } from "@bigbinary/neeto-commons-frontend/react-utils";
+ * 
+ * // Create a ref for the input field using useFieldSubmit
  * const inputRef = useFieldSubmit(() => {
  *   const inputValue = inputRef.current.value;
  *   console.log(inputValue);
@@ -409,42 +616,61 @@ export declare type ZustandStoreHook = UseBoundStore<StoreApi<any>> & {
  * 
  * return <textarea ref={inputRef} />;
  * @endexample
+ * When the Enter key is pressed, the onSubmit callback function is executed,
+ *
+ * allowing you to access the input value and perform the desired action.
+ *
 */
 export function useFieldSubmit(onSubmit: () => any): {
   current: HTMLInputElement & HTMLTextAreaElement;
 };
 /**
  *
- * An HOC which sets the browser title with the given value when the wrapped
+ * withTitle is an HOC which sets the browser title with the given value when the
  *
- * component is rendered. If title is not explicitly provided, it will render
+ * wrapped component is rendered. If title is not explicitly provided, it will
  *
- * globalProps.appName as the page title.
+ * render globalProps.appName as the page title.
  *
  * @example 
  *
  * // assume this code in neetoStore
  * const ProductsPage = props => <>Your page content here</>;
- * export default withTitle(ProductsPage, "All products");
+ * 
  * // will set the browser title to `All products | neetoStore` when this page is rendered.
+ * export default withTitle(ProductsPage, "All products");
  * @endexample
 */
 export function withTitle<T>(Component: React.ComponentType<T>, title?: string | null): (props: T) => JSX.Element;
 /**
  *
- * A browser push notifications utility function which asks the user permissions to
+ * registerBrowserNotifications is a browser push notifications utility function
+ *
+ * which asks the user permissions to send notifications and then register the
+ *
+ * browser with the notification service.
+ *
+ * To enable the notification service to dispatch web push messages to browsers, it
+ *
+ * relies on VAPID keys. These
+ *
+ * keys should be securely stored as environment variables and made accessible
+ *
+ * through process.env. If keys are not accessible from process.env, pass in
  *
- * send notifications and then register the browser with the notification service.
+ * the vapidPublicKey using global props from application helper.
  *
- * The VAPID public key.
+ * You can find the VAPID keys (PUBLIC and PRIVATE) for neeto products at
+ *
+ * neetoNotifications Dashboard.
  *
  * After the user logs in, we need to ask the user permissions to send
  *
- * notifications and then register the browser with the notification service.
+ * notifications and then register the browser with the notification service. The
  *
- * You can use the registerBrowserNotifications utility function to do this. It
+ * registerBrowserNotifications utility function facilitates this process. It can
  *
- * can be called on any event after login based on the application's logic and
+ * be called on any event after login based on the application's logic and
  *
  * requirement.
  *
@@ -478,23 +704,23 @@ export function withTitle<T>(Component: React.ComponentType<T>, title?: string |
 export async function registerBrowserNotifications(): Promise<void>;
 /**
  *
- * A browser push notifications utility function which destroys the browser
+ * destroyBrowserSubscription is a browser push notifications utility function
  *
- * subscriptions from the user's devices. This helps in unsubscribing from browser
+ * which destroys the browser subscriptions from the user's devices. This helps in
  *
- * push notifications.
+ * unsubscribing from browser push notifications.
  *
  * When the browser subscriptions expires for the user's devices or when the user
  *
- * decides to logout,then destroy the generated browser subscription for the user.
+ * decides to logout, the generated browser subscription for the user should be
  *
- * You can use the destroyBrowserSubscription utility function to do this. It can
+ * destroyed. The destroyBrowserSubscription utility function enables us to do
  *
- * be called on any event before logout based on the application's logic and
+ * the same. It can be called on any event before logout based on the application's
  *
- * requirement.
+ * logic and requirement.
  *
- * Here as an example: In the Logout component, we are calling
+ * Here is an example: In the Logout component, we are calling
  *
  * destroyBrowserSubscription method before the Logout API request. This
  *
@@ -524,72 +750,157 @@ export async function registerBrowserNotifications(): Promise<void>;
 export async function destroyBrowserSubscription(): Promise<void>;
 /**
  *
- * Curried: true
+ * The handleMetaClick function can be used to handle onClick actions that
+ *
+ * redirects to a URL. It opens up the URL in a new tab if ctrl/cmd + click event
+ *
+ * is received. Otherwise, simply redirects to the provided URL in the same tab.
  *
- * This function can be used to handle onClick actions that redirects to a URL.
+ * URL can be passed as string or a history location object can be passed instead.
  *
- * It opens up the URL in a new tab if ctrl/cmd + click event is received.
+ * Let's say you have a navigation menu with several links, and you want to allow
  *
- * Otherwise, simply redirects to the provided URL in the same tab. URL can be
+ * users to open these links in a new tab if they hold down the Ctrl (or Cmd on
  *
- * passed as string or a history location object can be passed instead.
+ * macOS) key while clicking, and if they click without holding down the Ctrl key,
+ *
+ * the link should open in the same tab. You can use handleMetaClick to achieve
+ *
+ * this behavior.
  *
  * @example 
  *
- * handleMetaClick(history, "/dashboard", e); //Opens "/dashboard" in a new tab if metaKey/CtrlKey is pressed. Otherwise simply redirects to "/dashboard".
- * handleMetaClick(history, { pathname: "/dashboard", state: "abc" }, e); //Opens "/dashboard" in a new tab if metaKey/CtrlKey is pressed. Otherwise, redirects to "/dashboard" by preserving the state.
+ * const NavigationMenu = () => {
+ *   const history = useHistory();
+ * 
+ *   const handleLinkClick = (url, event) => {
+ *     // Opens url in a new tab if metaKey/CtrlKey is pressed.
+ *     // Otherwise simply redirects to url.
+ *     handleMetaClick(history, url, event);
+ *   };
+ * 
+ *   return (
+ *     <div>
+ *       <a href="/home" onClick={e => handleLinkClick("/home", e)}>
+ *         Home
+ *       </a>
+ *       <a href="/dashboard" onClick={e => handleLinkClick("/dashboard", e)}>
+ *         Dashboard
+ *       </a>
+ *       <a href="/profile" onClick={e => handleLinkClick("/profile", e)}>
+ *         Profile
+ *       </a>
+ *     </div>
+ *   );
+ * };
  * @endexample
 */
 export function handleMetaClick(history: History, params: string | object, event: React.MouseEvent<HTMLElement, MouseEvent>): void;
 /**
  *
- * Curried: true
+ * The handleMetaClick function can be used to handle onClick actions that
+ *
+ * redirects to a URL. It opens up the URL in a new tab if ctrl/cmd + click event
  *
- * This function can be used to handle onClick actions that redirects to a URL.
+ * is received. Otherwise, simply redirects to the provided URL in the same tab.
  *
- * It opens up the URL in a new tab if ctrl/cmd + click event is received.
+ * URL can be passed as string or a history location object can be passed instead.
  *
- * Otherwise, simply redirects to the provided URL in the same tab. URL can be
+ * Let's say you have a navigation menu with several links, and you want to allow
  *
- * passed as string or a history location object can be passed instead.
+ * users to open these links in a new tab if they hold down the Ctrl (or Cmd on
+ *
+ * macOS) key while clicking, and if they click without holding down the Ctrl key,
+ *
+ * the link should open in the same tab. You can use handleMetaClick to achieve
+ *
+ * this behavior.
  *
  * @example 
  *
- * handleMetaClick(history, "/dashboard", e); //Opens "/dashboard" in a new tab if metaKey/CtrlKey is pressed. Otherwise simply redirects to "/dashboard".
- * handleMetaClick(history, { pathname: "/dashboard", state: "abc" }, e); //Opens "/dashboard" in a new tab if metaKey/CtrlKey is pressed. Otherwise, redirects to "/dashboard" by preserving the state.
+ * const NavigationMenu = () => {
+ *   const history = useHistory();
+ * 
+ *   const handleLinkClick = (url, event) => {
+ *     // Opens url in a new tab if metaKey/CtrlKey is pressed.
+ *     // Otherwise simply redirects to url.
+ *     handleMetaClick(history, url, event);
+ *   };
+ * 
+ *   return (
+ *     <div>
+ *       <a href="/home" onClick={e => handleLinkClick("/home", e)}>
+ *         Home
+ *       </a>
+ *       <a href="/dashboard" onClick={e => handleLinkClick("/dashboard", e)}>
+ *         Dashboard
+ *       </a>
+ *       <a href="/profile" onClick={e => handleLinkClick("/profile", e)}>
+ *         Profile
+ *       </a>
+ *     </div>
+ *   );
+ * };
  * @endexample
 */
 export function handleMetaClick(history: History, params: string | object): (event: React.MouseEvent<HTMLElement, MouseEvent>) => void;
 /**
  *
- * Curried: true
+ * The handleMetaClick function can be used to handle onClick actions that
+ *
+ * redirects to a URL. It opens up the URL in a new tab if ctrl/cmd + click event
  *
- * This function can be used to handle onClick actions that redirects to a URL.
+ * is received. Otherwise, simply redirects to the provided URL in the same tab.
  *
- * It opens up the URL in a new tab if ctrl/cmd + click event is received.
+ * URL can be passed as string or a history location object can be passed instead.
  *
- * Otherwise, simply redirects to the provided URL in the same tab. URL can be
+ * Let's say you have a navigation menu with several links, and you want to allow
  *
- * passed as string or a history location object can be passed instead.
+ * users to open these links in a new tab if they hold down the Ctrl (or Cmd on
+ *
+ * macOS) key while clicking, and if they click without holding down the Ctrl key,
+ *
+ * the link should open in the same tab. You can use handleMetaClick to achieve
+ *
+ * this behavior.
  *
  * @example 
  *
- * handleMetaClick(history, "/dashboard", e); //Opens "/dashboard" in a new tab if metaKey/CtrlKey is pressed. Otherwise simply redirects to "/dashboard".
- * handleMetaClick(history, { pathname: "/dashboard", state: "abc" }, e); //Opens "/dashboard" in a new tab if metaKey/CtrlKey is pressed. Otherwise, redirects to "/dashboard" by preserving the state.
+ * const NavigationMenu = () => {
+ *   const history = useHistory();
+ * 
+ *   const handleLinkClick = (url, event) => {
+ *     // Opens url in a new tab if metaKey/CtrlKey is pressed.
+ *     // Otherwise simply redirects to url.
+ *     handleMetaClick(history, url, event);
+ *   };
+ * 
+ *   return (
+ *     <div>
+ *       <a href="/home" onClick={e => handleLinkClick("/home", e)}>
+ *         Home
+ *       </a>
+ *       <a href="/dashboard" onClick={e => handleLinkClick("/dashboard", e)}>
+ *         Dashboard
+ *       </a>
+ *       <a href="/profile" onClick={e => handleLinkClick("/profile", e)}>
+ *         Profile
+ *       </a>
+ *     </div>
+ *   );
+ * };
  * @endexample
 */
 export function handleMetaClick(history: History): (params: string | object, event: React.MouseEvent<HTMLElement, MouseEvent>) => void;
 /**
  *
- * Curried: false
- *
- * This function can be used to check whether an onClick event has metaKey or
+ * The isMetaKeyPressed function can be used to check whether an onClick event
  *
- * ctrlKey pressed.
+ * has metaKey or ctrlKey pressed.
  *
  * @example 
  *
- * isMetaKeyPressed(event); //returns true if "event.metaKey || event.ctrlKey" is true, otherwise returns false.
+ * isMetaKeyPressed(event);
  * @endexample
 */
 export function isMetaKeyPressed(event: React.MouseEvent<HTMLElement, MouseEvent>): boolean;
@@ -600,14 +911,24 @@ type ConfigType = {
 };
 /**
  *
- * This is a configurable hook used for handling hotkeys in an application. We
+ * The useHotKeys hook is a versatile utility for handling hotkeys in an
+ *
+ * application. It allows you to define specific hotkey combinations and associate
+ *
+ * them with handler functions. When the user presses the configured hotkey(s), the
+ *
+ * corresponding handler is invoked, enabling you to perform actions in response to
+ *
+ * keyboard input.
  *
- * specify a hotkey and handler, whenever the hotkey is pressed by the user the
+ * Following illustrates the usage of useHotKeys in implementing shortcut for
  *
- * corresponding handler will be invoked.
+ * Sidebar opening.
  *
  * @example 
  *
+ * import { useHotKeys } from "@bigbinary/neeto-commons-frontend/react-utils";
+ * 
  * // openSidebar function will only be called if the user is focused inside the textarea and performs the key combination.
  * const ref = useHotKeys("command+shift+r", openSidebar, {
  *   mode: "scoped",
@@ -620,15 +941,33 @@ type ConfigType = {
  *   </div>
  * );
  * @endexample
+ * Hotkeys are a fundamental aspect of many applications, enhancing user efficiency
+ *
+ * and interactivity. The useHotKeys hook simplifies the implementation of these
+ *
+ * hotkeys by allowing you to specify the hotkey combinations in various formats,
+ *
+ * associated handlers, and configuration options.
+ *
 */
 export function useHotKeys(hotkey: string | string[], handler: (event: React.KeyboardEvent) => void, config?: ConfigType): React.MutableRefObject | null;
 /**
  *
- * This hook returns a state that automatically updates its value to defaultValue
+ * The useStateWithDependency hook is a utility that returns a state variable and
+ *
+ * a setter function similar to the useState hook. However, it provides
+ *
+ * additional functionality: the state variable automatically updates its value to
  *
- * whenever defaultValue changes. We can also specify a dependencies array to
+ * the specified defaultValue whenever defaultValue changes. Optionally, you
  *
- * listen to other variable changes.
+ * can also specify a dependencies array to listen for changes in other variables,
+ *
+ * which will trigger the update of the state variable.
+ *
+ * This hook will return an array with exactly two values just like useState
+ *
+ * hook.
  *
  * If dependencies is passed, the hook returns a state variable whose value will
  *
@@ -638,68 +977,221 @@ export function useHotKeys(hotkey: string | string[], handler: (event: React.Key
  *
  * @example 
  *
- * const [value, setValue] = useStateWithDependency(defaultValue); // reset state to `defaultValue` whenever `defaultValue` changes.
+ * import { useStateWithDependency } from "@bigbinary/neeto-commons-frontend/react-utils";
+ * 
+ * // reset state to `defaultValue` whenever `defaultValue` changes.
+ * const [value, setValue] = useStateWithDependency(defaultValue);
+ * 
+ * // reset state to `defaultValue` only when `value1` or `value2` changes.
  * const [value, setValue] = useStateWithDependency(defaultValue, [
  *   value1,
  *   value2,
- * ]); // reset state to `defaultValue` only when `value1` or `value2` changes.
+ * ]);
  * 
- * // In a case, where the value needs to be reset when defaultValue changes too, defaultValue can be passed with the dependencies, as shown below.
+ * // In a case, where the value needs to be reset when defaultValue
+ * // changes too, defaultValue can be passed with the dependencies,
+ * // as shown below.
  * const [value, setValue] = useStateWithDependency(defaultValue, [
  *   value1,
  *   value2,
  *   defaultValue,
  * ]);
  * @endexample
+ * The following code snippet demonstrates the usage of useStateWithDependency in
+ *
+ * ensuring that inputValue stays in sync with the value prop in the Rename
+ *
+ * component.
+ *
+ * @example 
+ *
+ * const Rename = ({ value }) => {
+ *   // Use the useStateWithDependency hook to manage the input value
+ *   const [inputValue, setInputValue] = useStateWithDependency(value);
+ * 
+ *   // Define a handler to update the input value
+ *   const handleInputChange = event => {
+ *     setInputValue(event.target.value);
+ *   };
+ * 
+ *   return (
+ *     <div>
+ *       <input type="text" value={inputValue} onChange={handleInputChange} />
+ *       { Rest of the component }
+ *     </div>
+ *   );
+ * };
+ * @endexample
+ * As the user interacts with the input field, the inputValue state is updated to
+ *
+ * reflect the user's input. In a scenario where the value prop changes from
+ *
+ * outside the Rename component, it triggers a re-render of the Rename
+ *
+ * component. When this re-render occurs, the inputValue state is automatically
+ *
+ * updated to match the new value prop.
+ *
 */
 export function useStateWithDependency<T>(defaultValue: T, dependencies?: any[]): T;
 /**
  *
- * This hook will store the path as the value for the key in a Zustand store.
+ * The useRegisterNavigationCheckpoint hook is a utility for storing navigation
  *
- * This registered checkpoint can be retrieved using the useNavigationCheckpoints
+ * checkpoints in a Zustand store. A navigation checkpoint consists of a key that
  *
- * hook.
+ * identifies the checkpoint and a corresponding path to be stored in the Zustand
+ *
+ * store under that key. These registered checkpoints can be later retrieved using
+ *
+ * the useNavigationCheckpoints hook.
+ *
+ * In web applications, scenarios frequently arise where it's essential to maintain
+ *
+ * user preferences and specific application states as users navigate back and
+ *
+ * forth between different routes.
+ *
+ * A simple button, that hard codes the route as <Link to="/resource" />, won't
+ *
+ * suffice in such scenarios to navigate between pages since it won't retain any
+ *
+ * filter, search, or pagination information.
+ *
+ * This is why we have checkpoints. When a page component is mounted, a checkpoint
+ *
+ * is registered to capture the current state of the page, including the URL with
+ *
+ * applied filters, search parameters, and pagination information. If the URL
+ *
+ * changes due to user interactions, the checkpoint is automatically updated.
+ *
+ * When a user presses the back button, the value stored in the checkpoint is used
+ *
+ * as the URL. This ensures that users return to the listing page with all their
+ *
+ * previous context intact, providing a seamless and user-friendly experience.
+ *
+ * Following code snippet illustrates the usage of
+ *
+ * useRegisterNavigationCheckpoint in retaining user preference and context.
  *
  * @example 
  *
- * useRegisterNavigationCheckpoint(CHECKPOINT_KEY, CHECKPOINT_PATH);
+ * // Import the useRegisterNavigationCheckpoint hook
+ * import { useRegisterNavigationCheckpoint } from "@bigbinary/neeto-commons-frontend/react-utils";
+ * // ...
+ * 
+ * // Register a navigation checkpoint with a key and path
+ * useRegisterNavigationCheckpoint(
+ *   NAVIGATION_CHECKPOINT_KEYS.ARTICLES,
+ *   window.location.pathname + window.location.search
+ * );
+ * @endexample
+ * When users visit the articles page, apply specific filters, and navigate away,
+ *
+ * the navigation checkpoint captures the current URL path along with the query
+ *
+ * parameters associated with the applied filters. Later, when users return to the
+ *
+ * page, the useNavigationCheckpoints hook can retrieve the saved checkpoint
+ *
+ * using the NAVIGATION_CHECKPOINT_KEYS.ARTICLES key. This retrieved data
+ *
+ * includes the applied filters, which can then be displayed on the articles page.
+ *
+ * It is worth noting that, at BigBinary, we define the object
+ *
+ * NAVIGATION_CHECKPOINT_KEYS to store the check point keys like so:
+ *
+ * @example 
+ *
+ * export const NAVIGATION_CHECKPOINT_KEYS = {
+ *   HOME: "home",
+ *   ARTICLES: "articles",
+ * };
  * @endexample
 */
 export function useRegisterNavigationCheckpoint(key: string, path: string): void;
 /**
  *
- * This function returns the specified navigation checkpoints.
+ * The useNavigationCheckpoints hook is a convenient tool for fetching designated
+ *
+ * navigation checkpoints stored in a Zustand store.
+ *
+ * In web applications, users frequently move between various pages or routes, and
+ *
+ * useRegisterNavigationCheckpoint empowers us to store particular paths or
+ *
+ * states as checkpoints. By employing the useNavigationCheckpoints hook, you can
+ *
+ * access these checkpoints by specifying their associated keys.
+ *
+ * We recommend reviewing the documentation for the
+ *
+ * useRegisterNavigationCheckpoint hook to
+ *
+ * gain a deeper understanding of the checkpoint concept.
+ *
+ * The following code snippet demonstrates the usage of useNavigationCheckpoints
+ *
+ * in retrieving navigation links that reflect the application's state and history.
  *
  * @example 
  *
- * const navigationCheckpoints = useNavigationCheckpoints(
- *   checkpointKey1,
- *   checkpointKey2
- * );
+ * // Import the useNavigationCheckpoints hook
+ * import { useNavigationCheckpoints } from "@bigbinary/neeto-commons-frontend/react-utils";
+ * 
+ * const navigationCheckpoints = useNavigationCheckpoints("home");
  * 
  * return (
  *   <>
- *     <Link to={navigationCheckpoints[checkpointKey1]}>Navigate</Link>
+ *     <Link to={navigationCheckpoints["home"]}>Home</Link>
  *   </>
  * );
  * @endexample
+ * The above code fetches navigation checkpoint data for the home key using the
+ *
+ * useNavigationCheckpoints hook and then renders a link labeled "Home" that,
+ *
+ * when clicked, will navigate the user to the URL associated with the home
+ *
+ * navigation checkpoint.
+ *
 */
 export function useNavigationCheckpoints(...keys: string[]): {
   [key: string]: string;
 };
 /**
  *
- * Similar to useDebounce but this hook accepts a function as an argument. That
+ * The useFuncDebounce hook is a utility that extends the benefits of debouncing
+ *
+ * to functions.
+ *
+ * When the debounced function is called, it sets a timer to execute the original
+ *
+ * function after a specified delay. If the debounced function is called again
+ *
+ * before the timer expires, the previous timer is cleared. This effectively delays
+ *
+ * the execution of the original function until the debounced function hasn't been
+ *
+ * called for the specified delay period.
+ *
+ * The hook also provides a cancel method to manually cancel the execution of the
+ *
+ * debounced function before it triggers.
  *
- * function will be executed only when the dependencies stops changing for a while.
+ * The following code snippet demonstrates the usage of useFuncDebounce in the
  *
- * The debounced function comes with a cancel method which can be used to cancel
+ * delaying the invocation of the fetch method until the user pauses typing for a
  *
- * the delayed function invocation.
+ * specific period.
  *
  * @example 
  *
+ * import { useFuncDebounce } from "@bigbinary/neeto-commons-frontend/react-utils";
+ * 
  * const searchForProducts = useFuncDebounce(async key => {
  *   // this function will be triggered once after user stops typing for 300ms
  *   const products = await productsApi.fetch(key);
@@ -717,15 +1209,17 @@ export const useFuncDebounce: {
 };
 /**
  *
- * usePersistedQuery is an wrapper function around useQuery hook from
+ * usePersistedQuery is an wrapper function around
+ *
+ * useQuery hook
  *
- * react-query. In addition to all the functionalities offered useQuery, this
+ * from react-query. In addition to all the functionalities offered useQuery,
  *
- * hook also stores the received response in localStorage. For subsequent page
+ * this hook also stores the received response in localStorage. For subsequent
  *
- * loads, the hook will be serving data from localStorage until the API response
+ * page loads, the hook will be serving data from localStorage until the API
  *
- * is received.
+ * response is received.
  *
  * usePersistedQuery will use the staleTime config from options parameter (if
  *
@@ -745,8 +1239,16 @@ export const useFuncDebounce: {
  *
  * by providing the queryKey.
  *
+ * The following code snippet demonstrates the usage of usePersistedQuery in
+ *
+ * caching API responses and serving cached data while waiting for fresh data from
+ *
+ * the APIs.
+ *
  * @example 
  *
+ * import { usePersistedQuery } from "@bigbinary/neeto-commons-frontend/react-utils";
+ * 
  * const useFetchUsers = options =>
  *   usePersistedQuery(QUERY_KEYS.FETCH_USERS, usersApi.fetch, options);
  * 
@@ -765,20 +1267,28 @@ export const usePersistedQuery: {
 };
 /**
  *
- * This hook fetches the list of neetoApps and isOwner flag from
+ * The useFetchNeetoApps hook calls
+ *
+ * neeto_apps_controller
+ *
+ * and fetches the response. neeto_apps_controller will return two information:
  *
- * neeto_apps_controller.
+ * This hook uses usePersistedQuery under the hood. So
  *
- * This hook uses usePersistedQuery under the hood. So data will be immediately
+ * data will be immediately available except for the first page load. Additionally
  *
- * available except for the first page load. Additionally if the data is available
+ * if the data is available in localStorage, it will be served from there until an
  *
- * in localStorage, it will be served from there until an explicit call to
+ * explicit call to refetch is made.
  *
- * refetch is made.
+ * The following code snippet shows the usage of useFetchNeetoApps in fetching
+ *
+ * neetoApps and ownership status.
  *
  * @example 
  *
+ * import { useFetchNeetoApps } from "@bigbinary/neeto-commons-frontend/react-utils";
+ * 
  * const { neetoApps, isOwner } = useFetchNeetoApps();
  * @endexample
 */
@@ -792,13 +1302,18 @@ export function useFetchNeetoApps(options?: UseQueryOptions): ReturnType<typeof
 }>>;
 /**
  *
- * An HOC which provides the t function from react-i18next to the wrapped
+ * withT is an HOC which provides the t function from react-i18next to the
+ *
+ * wrapped component as a prop. withT HOC should only be used in dumb components
+ *
+ * i.e, components which have no logic other than rendering something and the
  *
- * component as a prop.
+ * useTranslation hook.
  *
  * @example 
  *
- * const Component = withT(({ t }) => <div>{t("some.key")}</div>);
+ * // Example usage of withT:
+ * const ComponentWithTranslation = withT(({ t }) => <div>{t("some.key")}</div>);
  * @endexample
 */
 export const withT: <Props extends {
@@ -808,12 +1323,18 @@ export const withT: <Props extends {
 }>) => React.ComponentType<Props>;
 /**
  *
- * useMutationWithInvalidation is a wrapper function around the useMutation
+ * useMutationWithInvalidation is a wrapper function around the
+ *
+ * useMutation
  *
  * hook from react-query. It returns all the props from the useMutation hook and
  *
  * additionally, invalidates a list of query keys on mutation success.
  *
+ * The following code snippet illustrates the usage of
+ *
+ * useMutationWithInvalidation across various scenarios.
+ *
  * @example 
  *
  * // useQuestionsApi