docs(hooks): improved jsdoc examples

Author: João Dias

docs/docs/hooks/use-live-ref.mdx

@@ -3,6 +3,12 @@ title: useLifecycle
 ---
 Creates a `React.RefObject` that is constantly updated with the incoming value.
 
+React's useRef hook, primarily used for accessing DOM nodes or React elements, has another valuable application: stabilizing references.
+
+By wrapping volatile references in a stable container, useRef allows developers to grant dependencies immunity to change, which is particularly useful when you don't want hooks to trigger on every variable change.
+
+This technique is especially beneficial when working with hooks like useEffect. For instance, when dealing with side effects that depend on changing variables, using useRef can prevent unnecessary re-evaluations and ensure  more consistent behavior. A custom hook like useLiveRef can be implemented to provide a stable reference to changing values, offering finer control over when hooks are re-evaluated without compromising the integrity of dependency arrays or ESLint rules.
+
 ## API
 
 ```typescript

docs/docs/hooks/use-merge-refs.mdx

@@ -1,7 +1,13 @@
 ---
 title: useMergeRefs
 ---
-Returns a function that receives the element and assign the value to the given React refs.
+The `useMergeRefs` hook is designed to combine multiple React refs into a single callback ref.
+
+This is particularly useful when you need to apply multiple refs to a single element, such as when working with both internal component logic and external ref forwarding.
+
+By merging refs, you can maintain the functionality of each individual ref while avoiding conflicts or overrides that might occur when attempting to assign multiple refs directly.
+
+This hook enhances component flexibility and reusability, allowing developers to easily integrate both component-specific refs and externally provided refs in a clean, efficient manner.
 
 ## API
 

src/functions/events/custom-events/use-custom-event-listener.ts

@@ -11,9 +11,13 @@ import { getElement } from "./get-element";
  * A custom hook that listens to a custom event and auto-cleans itself on unmount.
  *
  * @example
+ * ```tsx
+ * import { useCustomEventListener } from "@feedzai/js-utilities/hooks";
+ * ...
  * useCustomEventListener('a-custom-event-name', data => {
  * 	doSomethingWithData( data );
  * });
+ * ```
  */
 export function useCustomEventListener<GenericType>(
   eventName: string,

src/hooks/use-auto-id.ts

@@ -30,10 +30,14 @@ function generateIncrementalId() {
  * component mounts. Users may need to supply their own ID if they need
  * consistent values for SSR.
  *
- * @example
+ * Note: The id generating mechanism uses `useId` under the hook, if on React 18+.
  *
+ * @example
+ * ```tsx
+ * import { useAutoId } from '@feedzai/js-utilities/hooks';
+ * ...
  * // Generating an id (no pre-defined id and no prefix)
- * const id1 = useAutoId(); // will return, for example, "0"
+ * const id1 = useAutoId(); // will return, for example,  "0" (or :r0: if on React 18+)
  *
  * // Using a pre-defined id (no prefix)
  * const id2 = useAutoId("8e88aa2e-e6a8") // will return "8e88aa2e-e6a8"
@@ -43,7 +47,7 @@ function generateIncrementalId() {
  *
  * // Using a prefix with a pre-defined id
  * const id4 = useAutoId("6949d175", "fdz-js-checkbox") // will return "fdz-js-checkbox--6949d175"
- *
+ *``
  * @param {string | null | undefined} customId - You can pass an previously defined value
  * and that value will be used as the value of the returned id.
  * @param {string | undefined} prefix - If necessary, you can prepend a generated id with a prefix.

src/hooks/use-click-outside.ts

@@ -13,11 +13,15 @@ import React, { useEffect } from "react";
  * the callback function.
  *
  * @example
+ * ```tsx
+ * import { useClickOutside } from '@feedzai/js-utilities/hooks';
+ * ...
  * useClickOutside(
-    DROPDROWN_REF,
-    () => closeDropdown(),
-    shouldClose,
-   );
+ *  DROPDROWN_REF,
+ *  () => closeDropdown(),
+ *  shouldClose,
+ * );
+ * ```
  */
 export function useClickOutside<GenericElement extends Element = HTMLElement>(
   ref: React.Ref<GenericElement>,
@@ -27,7 +31,7 @@ export function useClickOutside<GenericElement extends Element = HTMLElement>(
   useEffect(
     () => {
       const listener = <GenericEvent extends Event>(event: GenericEvent) => {
-        // @ts-ignore Do nothing if clicking ref's element or descendent elements
+        // @ts-expect-error Do nothing if clicking ref's element or descendent elements
         if (isNil(ref) || isNil(ref["current"]) || ref["current"].contains(event.target)) {
           return;
         }

src/hooks/use-constant.ts

@@ -12,6 +12,9 @@ import { useRef } from "react";
  * See {@link https://reactjs.org/docs/hooks-faq.html#how-to-create-expensive-objects-lazily this FAQ on React's own homepage}
  *
  * @example
+ * ```tsx
+ * import { useConstant } from '@feedzai/js-utilities/hooks';
+ * ...
  * // Calling the translateText function once
  * const messages = useConstant(() => {
  *  return {
@@ -22,9 +25,13 @@ import { useRef } from "react";
  *
  * // Consuming its unmodified value later on
  * <p>{messages.description}</p>
+ * ```
  *
  * @example
- *  const configs = useConstant(() => {
+ * ```tsx
+ * import { useConstant } from '@feedzai/js-utilities/hooks';
+ * ...
+ * const configs = useConstant(() => {
  *      const hasIcon = !isEmpty(icon);
  *      const iconClass = classNames("some-css-class", getIconClass(hasIcon, kind, icon));
  *
@@ -36,6 +43,7 @@ import { useRef } from "react";
  *
  * // Consuming its unmodified value later on
  * <p>{configs.hasIcon}</p>
+ * ```
  */
 export function useConstant<FunctionReturnType>(fn: () => FunctionReturnType): FunctionReturnType {
   const ref = useRef<{ instance: FunctionReturnType }>();

src/hooks/use-container-query/index.ts

@@ -23,7 +23,9 @@ import {
  * the size of a containing element rather than the size of the browser viewport.
  *
  * @example
- *
+ * ```jsx
+ * import { useContainerQuery } from "@feedzai/js-utilities/hooks";
+ * ...
  * const BREAKPOINTS = {
  *  "xs": [0, 960],
  *  "sm": [961, 1200],
@@ -42,7 +44,7 @@ import {
  *      </div>
  *   );
  * }
- *
+ * ```
  */
 export function useContainerQuery<GenericType extends HTMLElement>({
   breakpoints = DEFAULT_BREAKPOINTS,

src/hooks/use-controlled-state/index.ts

@@ -12,6 +12,18 @@ import { SetState } from "./types";
  * Check if a component is controlled or uncontrolled and returns the correct
  * state value and setter accordingly. If the component state is controlled by
  * the app, the setter is an empty function.
+ *
+ * @example
+ * ```tsx
+ * import { useControlledState } from '@feedzai/js-utilities/hooks';
+ * ...
+ * function Tabs(props) {
+ *  // The selected index can be defined by the Tabs internal state or a parent.
+ *  const [selectedIndex, setSelectedIndex] = useControlledState(
+ *    props.defaultIndex ?? DEFAULT_INITIAL_TAB_INDEX,
+ *    props.controlledIndex,
+ *  );
+ * ```
  */
 export function useControlledState<StateType>(
   defaultState: StateType | (() => StateType),

src/hooks/use-copy-to-clipboard.ts

@@ -32,12 +32,12 @@ function writeToClipboard(value: string) {
  * Copy text to a user's clipboard.
  *
  * @example
- * ```
- * import { useCopyToClipboard } from "@feedzai/js-utilities";
+ * ```tsx
+ * import { useCopyToClipboard } from "@feedzai/js-utilities/hooks";
  * ...
  * function Demo() {
  *  const [text, setText] = useState('');
- *  const { value, error, copyToClipboard } = useCopyToClipboard();
+ *  const { value, error, copyToClipboard } = useCopyToClipboard();
  *
  *  return (
  *    <div>

src/hooks/use-effect-once.ts

@@ -11,8 +11,8 @@ import { EffectCallback, useEffect } from "react";
  * Runs an effect only once.
  *
  * @example
- * ```
- * import {useEffectOnce} from '@feedzai/js-utilities';
+ * ```tsx
+ * import {useEffectOnce} from '@feedzai/js-utilities/hooks';
  *
  * useEffectOnce(() => {
  *   console.log('This runs only one time, when mounting');

src/hooks/use-lifecycle.ts

@@ -10,8 +10,8 @@ import { isFunction } from "../index";
  * React lifecycle hook that calls mount and unmount callbacks, when component is mounted and un-mounted, respectively.
  *
  * @example
- * ```
- * import { useLifecycle } from "@feedzai/js-utilities";
+ * ```tsx
+ * import { useLifecycle } from "@feedzai/js-utilities/hooks";
  * ...
  * useLifecycle(
  *  () => console.log('runs on mount'),

src/hooks/use-live-ref.ts

@@ -6,12 +6,29 @@
 import { MutableRefObject, useRef, useLayoutEffect } from "react";
 
 /**
- * Creates a `React.RefObject` that is constantly updated with the incoming
- * value.
+ * Creates a `React.RefObject` that is constantly updated with the incoming value.
+ *
+ * React's useRef hook, primarily used for accessing DOM nodes or React elements, has another
+ * valuable application: stabilizing references.
+ *
+ * By wrapping volatile references in a stable container, useRef allows developers to grant dependencies
+ * immunity to change, which is particularly useful when you don't want hooks to trigger on every variable change.
+ *
+ * This technique is especially beneficial when working with hooks like useEffect. For instance, when dealing with
+ * side effects that depend on changing variables, using useRef can prevent unnecessary re-evaluations and ensure
+ * more consistent behavior. A custom hook like useLiveRef can be implemented to provide a stable reference to
+ * changing values, offering finer control over when hooks are re-evaluated without compromising the integrity of
+ * dependency arrays or ESLint rules.
+ *
  * @example
+ *
+ * ```tsx
+ * import { useLiveRef } from '@feedzai/js-utilities/hooks';
+ * ...
  * function Component({ prop }) {
  *   const propRef = useLiveRef(prop);
  * }
+ * ```
  */
 export function useLiveRef<T>(value: T): MutableRefObject<T> {
   const ref = useRef(value);

src/hooks/use-merge-refs.ts

@@ -44,11 +44,20 @@ export function mergeRefs<Generic = HTMLElement>(
 }
 
 /**
- * Returns a function that receives the element and assign the value to the given React refs.
+ * The useMergeRefs hook is designed to combine multiple React refs into a single callback ref.
  *
- * @example
+ * This is particularly useful when you need to apply multiple refs to a single element, such as when working with
+ * both internal component logic and external ref forwarding. By merging refs, you can maintain the functionality of
+ * each individual ref while avoiding conflicts or overrides that might occur when attempting to assign multiple
+ * refs directly.
  *
- * ```
+ * This hook enhances component flexibility and reusability, allowing developers to easily integrate both
+ * component-specific refs and externally provided refs in a clean, efficient manner.
+ *
+ * @example
+ * ```tsx
+ * import { useMergeRefs } from '@feedzai/js-utilities/hooks';
+ * ...
  * // a div with multiple refs
  * function Example({ ref, ...props }) {
  *   const internalRef = React.useRef();

src/hooks/use-mount.ts

@@ -10,7 +10,7 @@ import { useEffectOnce } from "./use-effect-once";
  *
  * @example
  * ```
- * import { useMount } from "@feedzai/js-utilities";
+ * import { useMount } from "@feedzai/js-utilities/hooks";
  * ...
  * useMount(() => {
  *  console.log("the component has mounted");

src/hooks/use-mounted-state.ts

@@ -11,7 +11,7 @@ import { useCallback, useEffect, useRef } from "react";
  *
  * @example
  * ```
- * import { useMountedState } from "@feedzai/js-utilities";
+ * import { useMountedState } from "@feedzai/js-utilities/hooks";
  * ...
  * const isMounted = useMountedState();
  *

src/hooks/use-network-state/index.ts

@@ -36,6 +36,9 @@ function getConnectionState(previousState?: UseNetworkState): UseNetworkState {
  * Tracks the state of browser's network connection.
  *
  * @example
+ * ```tsx
+ * import { useNetworkState } from '@feedzai/js-utilities/hooks';
+ * ...
  * const onlineState = useNetworkState();
  *
  * return (
@@ -44,6 +47,7 @@ function getConnectionState(previousState?: UseNetworkState): UseNetworkState {
  *    <pre>{JSON.stringify(onlineState, null, 2)}</pre>
  *  </div>
  * );
+ * ```
  */
 export function useNetworkState(initialState?: UseNetworkState): UseNetworkState {
   const [state, setState] = useState(initialState ?? getConnectionState);

src/hooks/use-page-visibility/index.ts

@@ -23,6 +23,9 @@ import { PageVisibilityCallback } from "./types";
  * d) A site wants to switch off sounds when a device is in standby mode (user pushes power button to turn screen off)
  *
  * @example
+ * ```tsx
+ * import { usePageVisibility } from '@feedzai/js-utilities/hooks';
+ * ...
  *  // When the user changes tabs, save the written note draft
  *  usePageVisibility((isVisible) => {
  *    if (!isVisible) {
@@ -36,9 +39,7 @@ import { PageVisibilityCallback } from "./types";
  *      saveNoteDraft();
  *    }
  *  }, 2000);
- *
- * @param {PageVisibilityCallback} handlerCallback Callback function to run when page visibility changes. A boolean value (indicating whether the page is visible or not) will be passed as an argument to this function.
- * @param {number} [delay] Number of milliseconds to wait before responding to page visibility change
+ * ```
  */
 export function usePageVisibility(handlerCallback: PageVisibilityCallback, delay?: number): void {
   const { current: BROWSER_COMPATIBILITY } = useRef(getBrowserCompatibility());

src/hooks/use-permission/index.ts

@@ -13,26 +13,22 @@ import { UsePermissionState } from "./types";
  * - Automatically updates on permission state change.
  *
  * @example
+ * ```tsx
+ * import { usePermission } from '@feedzai/js-utilities/hooks';
+ * ...
  * const status = usePermission({ name: 'notifications' });
-
-  return (
-    <div>
-      <div>
-        Notifications status: <code>{status}</code>
-      </div>
-      <div>
-        {status === 'prompt' && (
-          <button
-            onClick={() => {
-
-              Notification.requestPermission();
-            }}>
-            Request notifications permission
-          </button>
-        )}
-      </div>
-    </div>
-  );
+ *
+ * return (
+ *  <>
+ *   <p>Notifications status: <code>{status}</code></p>
+ *   {status === 'prompt' && (
+ *     <button type="button" onClick={() => Notification.requestPermission()}>
+ *       Request notifications permission
+ *     </button>
+ *   )}
+ *  </>
+ * );
+ * ```
  *
  * @param descriptor Permission request descriptor that passed to `navigator.permissions.query`
  */

src/hooks/use-previous.ts

@@ -8,6 +8,23 @@ import { useEffect, useRef } from "react";
 /**
  * React state hook that returns the previous state as described in the React hooks FAQ.
  * {@link https://reactjs.org/docs/hooks-faq.html#how-to-get-the-previous-props-or-state}
+ *
+ * @example
+ * ```tsx
+ * import { usePrevious } from '@feedzai/js-utilities/hooks';
+ * ...
+ * function Component() {
+ *  const [value, setValue] = useState(0);
+ *  const previousValue = usePrevious(value);
+ *
+ *  return (
+ *    <div>
+ *      <span>{previousValue}</span>
+ *      <button onClick={() => setValue((prev) => prev + 1)}>Increment</button>
+ *    </div>
+ *  );
+ * }
+ * ```
  */
 export function usePrevious<GenericType>(state: GenericType): GenericType | undefined {
   const ref = useRef<GenericType>();