@oneplatformdev/hooks 0.1.0-6 → 0.1.0-8

package/node_modules/@types/react/ts5.0/v18/ts5.0/jsx-dev-runtime.d.ts

@@ -0,0 +1,44 @@
+import * as React from "./";
+export { Fragment } from "./";
+
+export namespace JSX {
+    interface Element extends React.JSX.Element {}
+    interface ElementClass extends React.JSX.ElementClass {}
+    interface ElementAttributesProperty extends React.JSX.ElementAttributesProperty {}
+    interface ElementChildrenAttribute extends React.JSX.ElementChildrenAttribute {}
+    type LibraryManagedAttributes<C, P> = React.JSX.LibraryManagedAttributes<C, P>;
+    interface IntrinsicAttributes extends React.JSX.IntrinsicAttributes {}
+    interface IntrinsicClassAttributes<T> extends React.JSX.IntrinsicClassAttributes<T> {}
+    interface IntrinsicElements extends React.JSX.IntrinsicElements {}
+}
+
+export interface JSXSource {
+    /**
+     * The source file where the element originates from.
+     */
+    fileName?: string | undefined;
+
+    /**
+     * The line number where the element was created.
+     */
+    lineNumber?: number | undefined;
+
+    /**
+     * The column number where the element was created.
+     */
+    columnNumber?: number | undefined;
+}
+
+/**
+ * Create a React element.
+ *
+ * You should not use this function directly. Use JSX and a transpiler instead.
+ */
+export function jsxDEV(
+    type: React.ElementType,
+    props: unknown,
+    key: React.Key | undefined,
+    isStatic: boolean,
+    source?: JSXSource,
+    self?: unknown,
+): React.ReactElement;

package/node_modules/@types/react/ts5.0/v18/ts5.0/jsx-runtime.d.ts

@@ -0,0 +1,35 @@
+import * as React from "./";
+export { Fragment } from "./";
+
+export namespace JSX {
+    interface Element extends React.JSX.Element {}
+    interface ElementClass extends React.JSX.ElementClass {}
+    interface ElementAttributesProperty extends React.JSX.ElementAttributesProperty {}
+    interface ElementChildrenAttribute extends React.JSX.ElementChildrenAttribute {}
+    type LibraryManagedAttributes<C, P> = React.JSX.LibraryManagedAttributes<C, P>;
+    interface IntrinsicAttributes extends React.JSX.IntrinsicAttributes {}
+    interface IntrinsicClassAttributes<T> extends React.JSX.IntrinsicClassAttributes<T> {}
+    interface IntrinsicElements extends React.JSX.IntrinsicElements {}
+}
+
+/**
+ * Create a React element.
+ *
+ * You should not use this function directly. Use JSX and a transpiler instead.
+ */
+export function jsx(
+    type: React.ElementType,
+    props: unknown,
+    key?: React.Key,
+): React.ReactElement;
+
+/**
+ * Create a React element.
+ *
+ * You should not use this function directly. Use JSX and a transpiler instead.
+ */
+export function jsxs(
+    type: React.ElementType,
+    props: unknown,
+    key?: React.Key,
+): React.ReactElement;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oneplatformdev/hooks",
-  "version": "0.1.0-6",
+  "version": "0.1.0-8",
   "description": "React hook library",
   "author": "One Platform Development Team",
   "keywords": [
@@ -39,6 +39,7 @@
     }
   },
   "files": [
+    "**/*",
     "dist",
     "README.md",
     "LICENSE",

package/src/index.ts

@@ -0,0 +1,36 @@
+export * from './useBoolean';
+export * from './useClickAnyWhere';
+export * from './useCopyToClipboard';
+export * from './useCountdown';
+export * from './useCounter';
+export * from './useDarkMode';
+export * from './useDebounceCallback';
+export * from './useDebounceValue';
+export * from './useDocumentTitle';
+export * from './useEventCallback';
+export * from './useEventListener';
+export * from './useHover';
+export * from './useIntersectionObserver';
+export * from './useInterval';
+export * from './useIsClient';
+export * from './useIsMobile';
+export * from './useIsMounted';
+export * from './useIsomorphicLayoutEffect';
+export * from './useLocalStorage';
+export * from './useLockBody';
+export * from './useMap';
+export * from './useMediaQuery';
+export * from './useOnClickOutside';
+export * from './useReadLocalStorage';
+export * from './useResizeObserver';
+export * from './useScreen';
+export * from './useScript';
+export * from './useScrollLock';
+export * from './useSessionStorage';
+export * from './useStep';
+export * from './useTernaryDarkMode';
+export * from './useTimeout';
+export * from './useToggle';
+export * from './useUnmount';
+export * from './useWindowSize';
+export * from './useQueryString';

package/src/useBoolean/index.ts

@@ -0,0 +1 @@
+export * from './useBoolean'

package/src/useBoolean/useBoolean.ts

@@ -0,0 +1,50 @@
+import { useCallback, useState } from 'react'
+
+import type { Dispatch, SetStateAction } from 'react'
+
+/** The useBoolean return type. */
+type UseBooleanReturn = {
+  /** The current boolean state value. */
+  value: boolean
+  /** Function to set the boolean state directly. */
+  setValue: Dispatch<SetStateAction<boolean>>
+  /** Function to set the boolean state to `true`. */
+  setTrue: () => void
+  /** Function to set the boolean state to `false`. */
+  setFalse: () => void
+  /** Function to toggle the boolean state. */
+  toggle: () => void
+}
+
+/**
+ * Custom hook that handles boolean state with useful utility functions.
+ * @param {boolean} [defaultValue] - The initial value for the boolean state (default is `false`).
+ * @returns {UseBooleanReturn} An object containing the boolean state value and utility functions to manipulate the state.
+ * @throws Will throw an error if `defaultValue` is an invalid boolean value.
+ * @public
+ * @see [Documentation](https://usehooks-ts.com/react-hook/use-boolean)
+ * @example
+ * ```tsx
+ * const { value, setTrue, setFalse, toggle } = useBoolean(true);
+ * ```
+ */
+export function useBoolean(defaultValue = false): UseBooleanReturn {
+  if (typeof defaultValue !== 'boolean') {
+    throw new Error('defaultValue must be `true` or `false`')
+  }
+  const [value, setValue] = useState(defaultValue)
+
+  const setTrue = useCallback(() => {
+    setValue(true)
+  }, [])
+
+  const setFalse = useCallback(() => {
+    setValue(false)
+  }, [])
+
+  const toggle = useCallback(() => {
+    setValue(x => !x)
+  }, [])
+
+  return { value, setValue, setTrue, setFalse, toggle }
+}

package/src/useClickAnyWhere/index.ts

@@ -0,0 +1 @@
+export * from './useClickAnyWhere'

package/src/useClickAnyWhere/useClickAnyWhere.ts

@@ -0,0 +1,22 @@
+import { useEventListener } from '../useEventListener'
+
+/**
+ * Custom hook that handles click events anywhere on the document.
+ * @param {Function} handler - The function to be called when a click event is detected anywhere on the document.
+ * @public
+ * @see [Documentation](https://usehooks-ts.com/react-hook/use-click-any-where)
+ * @example
+ * ```tsx
+ * const handleClick = (event) => {
+ *   console.log('Document clicked!', event);
+ * };
+ *
+ * // Attach click event handler to document
+ * useClickAnywhere(handleClick);
+ * ```
+ */
+export function useClickAnyWhere(handler: (event: MouseEvent) => void) {
+  useEventListener('click', event => {
+    handler(event)
+  })
+}

package/src/useCopyToClipboard/index.ts

@@ -0,0 +1 @@
+export * from './useCopyToClipboard'

package/src/useCopyToClipboard/useCopyToClipboard.ts

@@ -0,0 +1,58 @@
+import { useCallback, useState } from 'react'
+
+/**
+ * The copied text as `string` or `null` if nothing has been copied yet.
+ */
+type CopiedValue = string | null
+
+/**
+ * Function to copy text to the clipboard.
+ * @param text - The text to copy to the clipboard.
+ * @returns {Promise<boolean>} A promise that resolves to `true` if the text was copied successfully, or `false` otherwise.
+ */
+type CopyFn = (text: string) => Promise<boolean>
+
+/**
+ * Custom hook that copies text to the clipboard using the [`Clipboard API`](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API).
+ * @returns {[CopiedValue, CopyFn]} An tuple containing the copied text and a function to copy text to the clipboard.
+ * @public
+ * @see [Documentation](https://usehooks-ts.com/react-hook/use-copy-to-clipboard)
+ * @example
+ * ```tsx
+ * const [copiedText, copyToClipboard] = useCopyToClipboard();
+ * const textToCopy = 'Hello, world!';
+ *
+ * // Attempt to copy text to the clipboard
+ * copyToClipboard(textToCopy)
+ *   .then(success => {
+ *     if (success) {
+ *       console.log(`Text "${textToCopy}" copied to clipboard successfully.`);
+ *     } else {
+ *       console.error('Failed to copy text to clipboard.');
+ *     }
+ *   });
+ * ```
+ */
+export function useCopyToClipboard(): [CopiedValue, CopyFn] {
+  const [copiedText, setCopiedText] = useState<CopiedValue>(null)
+
+  const copy: CopyFn = useCallback(async text => {
+    if (!navigator?.clipboard) {
+      console.warn('Clipboard not supported')
+      return false
+    }
+
+    // Try to save to clipboard then save it in the state if worked
+    try {
+      await navigator.clipboard.writeText(text)
+      setCopiedText(text)
+      return true
+    } catch (error) {
+      console.warn('Copy failed', error)
+      setCopiedText(null)
+      return false
+    }
+  }, [])
+
+  return [copiedText, copy]
+}

package/src/useCountdown/index.ts

@@ -0,0 +1 @@
+export * from './useCountdown'

package/src/useCountdown/useCountdown.ts

@@ -0,0 +1,102 @@
+import { useCallback } from 'react'
+
+import { useBoolean } from '../useBoolean'
+import { useCounter } from '../useCounter'
+import { useInterval } from '../useInterval'
+
+/** The countdown's options. */
+type CountdownOptions = {
+  /** The countdown's starting number, initial value of the returned number. */
+  countStart: number
+
+  /**
+   * The countdown's interval, in milliseconds.
+   * @default 1000
+   */
+  intervalMs?: number
+  /**
+   * True if the countdown is increment.
+   * @default false
+   */
+  isIncrement?: boolean
+
+  /**
+   * The countdown's stopping number. Pass `-Infinity` to decrease forever.
+   * @default 0
+   */
+  countStop?: number
+}
+
+/** The countdown's controllers. */
+type CountdownControllers = {
+  /** Start the countdown. */
+  startCountdown: () => void
+  /** Stop the countdown. */
+  stopCountdown: () => void
+  /** Reset the countdown. */
+  resetCountdown: () => void
+}
+
+/**
+ * Custom hook that manages countdown.
+ * @param {CountdownOptions} countdownOptions - The countdown's options.
+ * @returns {[number, CountdownControllers]} An array containing the countdown's count and its controllers.
+ * @public
+ * @see [Documentation](https://usehooks-ts.com/react-hook/use-countdown)
+ * @example
+ * ```tsx
+ * const [counter, { start, stop, reset }] = useCountdown({
+ *   countStart: 10,
+ *   intervalMs: 1000,
+ *   isIncrement: false,
+ * });
+ * ```
+ */
+export function useCountdown({
+  countStart,
+  countStop = 0,
+  intervalMs = 1000,
+  isIncrement = false,
+}: CountdownOptions): [number, CountdownControllers] {
+  const {
+    count,
+    increment,
+    decrement,
+    reset: resetCounter,
+  } = useCounter(countStart)
+
+  /*
+   * Note: used to control the useInterval
+   * running: If true, the interval is running
+   * start: Should set running true to trigger interval
+   * stop: Should set running false to remove interval.
+   */
+  const {
+    value: isCountdownRunning,
+    setTrue: startCountdown,
+    setFalse: stopCountdown,
+  } = useBoolean(false)
+
+  // Will set running false and reset the seconds to initial value.
+  const resetCountdown = useCallback(() => {
+    stopCountdown()
+    resetCounter()
+  }, [stopCountdown, resetCounter])
+
+  const countdownCallback = useCallback(() => {
+    if (count === countStop) {
+      stopCountdown()
+      return
+    }
+
+    if (isIncrement) {
+      increment()
+    } else {
+      decrement()
+    }
+  }, [count, countStop, decrement, increment, isIncrement, stopCountdown])
+
+  useInterval(countdownCallback, isCountdownRunning ? intervalMs : null)
+
+  return [count, { startCountdown, stopCountdown, resetCountdown }]
+}

package/src/useCounter/index.ts

@@ -0,0 +1 @@
+export * from './useCounter'

package/src/useCounter/useCounter.ts

@@ -0,0 +1,52 @@
+import { useCallback, useState } from 'react'
+
+import type { Dispatch, SetStateAction } from 'react'
+
+/** The hook return type. */
+type UseCounterReturn = {
+  /** The current count value. */
+  count: number
+  /** Function to increment the counter by 1. */
+  increment: () => void
+  /** Function to decrement the counter by 1. */
+  decrement: () => void
+  /** Function to reset the counter to its initial value. */
+  reset: () => void
+  /** Function to set a specific value to the counter. */
+  setCount: Dispatch<SetStateAction<number>>
+}
+
+/**
+ * Custom hook that manages a counter with increment, decrement, reset, and setCount functionalities.
+ * @param {number} [initialValue] - The initial value for the counter.
+ * @returns {UseCounterReturn} An object containing the current count and functions to interact with the counter.
+ * @public
+ * @see [Documentation](https://usehooks-ts.com/react-hook/use-counter)
+ * @example
+ * ```tsx
+ * const { count, increment, decrement, reset, setCount } = useCounter(5);
+ * ```
+ */
+export function useCounter(initialValue?: number): UseCounterReturn {
+  const [count, setCount] = useState(initialValue ?? 0)
+
+  const increment = useCallback(() => {
+    setCount(x => x + 1)
+  }, [])
+
+  const decrement = useCallback(() => {
+    setCount(x => x - 1)
+  }, [])
+
+  const reset = useCallback(() => {
+    setCount(initialValue ?? 0)
+  }, [initialValue])
+
+  return {
+    count,
+    increment,
+    decrement,
+    reset,
+    setCount,
+  }
+}

package/src/useDarkMode/index.ts

@@ -0,0 +1 @@
+export * from './useDarkMode'

package/src/useDarkMode/useDarkMode.ts

@@ -0,0 +1,92 @@
+import { useIsomorphicLayoutEffect } from '../useIsomorphicLayoutEffect'
+import { useLocalStorage } from '../useLocalStorage'
+import { useMediaQuery } from '../useMediaQuery'
+
+const COLOR_SCHEME_QUERY = '(prefers-color-scheme: dark)'
+const LOCAL_STORAGE_KEY = 'usehooks-ts-dark-mode'
+
+/** The hook options. */
+type DarkModeOptions = {
+  /**
+   * The initial value of the dark mode.
+   * @default false
+   */
+  defaultValue?: boolean
+  /**
+   * The key to use in the local storage.
+   * @default 'usehooks-ts-dark-mode'
+   */
+  localStorageKey?: string
+  /**
+   * If `true` (default), the hook will initialize reading `localStorage`.
+   * In SSR, you should set it to `false`, returning the `defaultValue` or `false` initially.
+   * @default true
+   */
+  initializeWithValue?: boolean
+}
+
+/** The hook return type. */
+type DarkModeReturn = {
+  /** The current state of the dark mode. */
+  isDarkMode: boolean
+  /** Function to toggle the dark mode. */
+  toggle: () => void
+  /** Function to enable the dark mode. */
+  enable: () => void
+  /** Function to disable the dark mode. */
+  disable: () => void
+  /** Function to set a specific value to the dark mode. */
+  set: (value: boolean) => void
+}
+
+/**
+ * Custom hook that returns the current state of the dark mode.
+ * @param {?DarkModeOptions} [options] - The initial value of the dark mode, default `false`.
+ * @returns {DarkModeReturn} An object containing the dark mode's state and its controllers.
+ * @public
+ * @see [Documentation](https://usehooks-ts.com/react-hook/use-dark-mode)
+ * @example
+ * ```tsx
+ * const { isDarkMode, toggle, enable, disable, set } = useDarkMode({ defaultValue: true });
+ * ```
+ */
+export function useDarkMode(options: DarkModeOptions = {}): DarkModeReturn {
+  const {
+    defaultValue,
+    localStorageKey = LOCAL_STORAGE_KEY,
+    initializeWithValue = true,
+  } = options
+
+  const isDarkOS = useMediaQuery(COLOR_SCHEME_QUERY, {
+    initializeWithValue,
+    defaultValue,
+  })
+  const [isDarkMode, setDarkMode] = useLocalStorage<boolean>(
+    localStorageKey,
+    defaultValue ?? isDarkOS ?? false,
+    { initializeWithValue },
+  )
+
+  // Update darkMode if os prefers changes
+  useIsomorphicLayoutEffect(() => {
+    if (isDarkOS !== isDarkMode) {
+      setDarkMode(isDarkOS)
+    }
+  }, [isDarkOS])
+
+  return {
+    isDarkMode,
+    toggle: () => {
+      setDarkMode(prev => !prev)
+    },
+    enable: () => {
+      setDarkMode(true)
+    },
+    disable: () => {
+      setDarkMode(false)
+    },
+    set: value => {
+      setDarkMode(value)
+    },
+  }
+}

package/src/useDebounceCallback/index.ts

@@ -0,0 +1,2 @@
+export * from './useDebounceCallback'
+export {useDebounceCallback as default } from './useDebounceCallback'

package/src/useDebounceCallback/useDebounceCallback.ts

@@ -0,0 +1,115 @@
+import { useEffect, useMemo, useRef } from 'react'
+
+import debounce from 'lodash.debounce'
+
+import { useUnmount } from '../useUnmount'
+
+/** Configuration options for controlling the behavior of the debounced function. */
+type DebounceOptions = {
+  /**
+   * Determines whether the function should be invoked on the leading edge of the timeout.
+   * @default false
+   */
+  leading?: boolean
+  /**
+   * Determines whether the function should be invoked on the trailing edge of the timeout.
+   * @default false
+   */
+  trailing?: boolean
+  /**
+   * The maximum time the specified function is allowed to be delayed before it is invoked.
+   */
+  maxWait?: number
+}
+
+/** Functions to manage a debounced callback. */
+type ControlFunctions = {
+  /** Cancels pending function invocations. */
+  cancel: () => void
+  /** Immediately invokes pending function invocations. */
+  flush: () => void
+  /**
+   * Checks if there are any pending function invocations.
+   * @returns `true` if there are pending invocations, otherwise `false`.
+   */
+  isPending: () => boolean
+}
+
+/**
+ * Represents the state and control functions of a debounced callback.
+ * Subsequent calls to the debounced function return the result of the last invocation.
+ * Note: If there are no previous invocations, the result will be undefined.
+ * Ensure proper handling in your code.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type DebouncedState<T extends (...args: any) => ReturnType<T>> = ((
+  ...args: Parameters<T>
+) => ReturnType<T> | undefined) &
+  ControlFunctions
+
+/**
+ * Custom hook that creates a debounced version of a callback function.
+ * @template T - Type of the original callback function.
+ * @param {T} func - The callback function to be debounced.
+ * @param {number} delay - The delay in milliseconds before the callback is invoked (default is `500` milliseconds).
+ * @param {DebounceOptions} [options] - Options to control the behavior of the debounced function.
+ * @returns {DebouncedState<T>} A debounced version of the original callback along with control functions.
+ * @public
+ * @see [Documentation](https://usehooks-ts.com/react-hook/use-debounce-callback)
+ * @example
+ * ```tsx
+ * const debouncedCallback = useDebounceCallback(
+ *   (searchTerm) => {
+ *     // Perform search after user stops typing for 500 milliseconds
+ *     searchApi(searchTerm);
+ *   },
+ *   500
+ * );
+ *
+ * // Later in the component
+ * debouncedCallback('react hooks'); // Will invoke the callback after 500 milliseconds of inactivity.
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function useDebounceCallback<T extends (...args: any) => ReturnType<T>>(
+  func: T,
+  delay = 500,
+  options?: DebounceOptions,
+): DebouncedState<T> {
+  const debouncedFunc = useRef<ReturnType<typeof debounce>>(null)
+
+  useUnmount(() => {
+    if (debouncedFunc.current) {
+      debouncedFunc.current.cancel()
+    }
+  })
+
+  const debounced = useMemo(() => {
+    const debouncedFuncInstance = debounce(func, delay, options)
+
+    const wrappedFunc: DebouncedState<T> = (...args: Parameters<T>) => {
+      return debouncedFuncInstance(...args)
+    }
+
+    wrappedFunc.cancel = () => {
+      debouncedFuncInstance.cancel()
+    }
+
+    wrappedFunc.isPending = () => {
+      return !!debouncedFunc.current
+    }
+
+    wrappedFunc.flush = () => {
+      return debouncedFuncInstance.flush()
+    }
+
+    return wrappedFunc
+  }, [func, delay, options])
+
+  // Update the debounced function ref whenever func, wait, or options change
+  useEffect(() => {
+    debouncedFunc.current = debounce(func, delay, options)
+  }, [func, delay, options])
+
+  return debounced
+}

package/src/useDebounceValue/index.ts

@@ -0,0 +1 @@
+export * from './useDebounceValue'