@oneplatformdev/ui 0.1.0-5 → 0.1.0-8

package/node_modules/@oneplatformdev/hooks/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/node_modules/@oneplatformdev/hooks/src/useDarkMode/index.ts

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

package/node_modules/@oneplatformdev/hooks/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/node_modules/@oneplatformdev/hooks/src/useDebounceCallback/index.ts

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

package/node_modules/@oneplatformdev/hooks/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/node_modules/@oneplatformdev/hooks/src/useDebounceValue/index.ts

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

package/node_modules/@oneplatformdev/hooks/src/useDebounceValue/useDebounceValue.ts

@@ -0,0 +1,67 @@
+import { useRef, useState } from 'react'
+
+import type { DebouncedState } from '../useDebounceCallback'
+import { useDebounceCallback } from '../useDebounceCallback'
+
+/**
+ * Hook options.
+ * @template T - The type of the value.
+ */
+type UseDebounceValueOptions<T> = {
+  /**
+   * 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
+  /** A function to determine if the value has changed. Defaults to a function that checks if the value is strictly equal to the previous value. */
+  equalityFn?: (left: T, right: T) => boolean
+}
+
+/**
+ * Custom hook that returns a debounced version of the provided value, along with a function to update it.
+ * @template T - The type of the value.
+ * @param {T | (() => T)} initialValue - The value to be debounced.
+ * @param {number} delay - The delay in milliseconds before the value is updated (default is 500ms).
+ * @param {object} [options] - Optional configurations for the debouncing behavior.
+ * @returns {[T, DebouncedState<(value: T) => void>]} An array containing the debounced value and the function to update it.
+ * @public
+ * @see [Documentation](https://usehooks-ts.com/react-hook/use-debounce-value)
+ * @example
+ * ```tsx
+ * const [debouncedValue, updateDebouncedValue] = useDebounceValue(inputValue, 500, { leading: true });
+ * ```
+ */
+export function useDebounceValue<T>(
+  initialValue: T | (() => T),
+  delay: number,
+  options?: UseDebounceValueOptions<T>,
+): [T, DebouncedState<(value: T) => void>] {
+  const eq = options?.equalityFn ?? ((left: T, right: T) => left === right)
+  const unwrappedInitialValue =
+    initialValue instanceof Function ? initialValue() : initialValue
+  const [debouncedValue, setDebouncedValue] = useState<T>(unwrappedInitialValue)
+  const previousValueRef = useRef<T | undefined>(unwrappedInitialValue)
+
+  const updateDebouncedValue = useDebounceCallback(
+    setDebouncedValue,
+    delay,
+    options,
+  )
+
+  // Update the debounced value if the initial value changes
+  if (!eq(previousValueRef.current as T, unwrappedInitialValue)) {
+    updateDebouncedValue(unwrappedInitialValue)
+    previousValueRef.current = unwrappedInitialValue
+  }
+
+  return [debouncedValue, updateDebouncedValue]
+}

package/node_modules/@oneplatformdev/hooks/src/useDocumentTitle/index.ts

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

package/node_modules/@oneplatformdev/hooks/src/useDocumentTitle/useDocumentTitle.ts

@@ -0,0 +1,43 @@
+import { useRef } from 'react'
+
+import { useIsomorphicLayoutEffect } from '../useIsomorphicLayoutEffect'
+import { useUnmount } from '../useUnmount'
+
+/** Hook options. */
+type UseDocumentTitleOptions = {
+  /** Whether to keep the title after unmounting the component (default is `true`). */
+  preserveTitleOnUnmount?: boolean
+}
+
+/**
+ * Custom hook that sets the document title.
+ * @param {string} title - The title to set.
+ * @param {?UseDocumentTitleOptions} [options] - The options.
+ * @public
+ * @see [Documentation](https://usehooks-ts.com/react-hook/use-document-title)
+ * @example
+ * ```tsx
+ * useDocumentTitle('My new title');
+ * ```
+ */
+export function useDocumentTitle(
+  title: string,
+  options: UseDocumentTitleOptions = {},
+): void {
+  const { preserveTitleOnUnmount = true } = options
+  const defaultTitle = useRef<string | null>(null)
+
+  useIsomorphicLayoutEffect(() => {
+    defaultTitle.current = window.document.title
+  }, [])
+
+  useIsomorphicLayoutEffect(() => {
+    window.document.title = title
+  }, [title])
+
+  useUnmount(() => {
+    if (!preserveTitleOnUnmount && defaultTitle.current) {
+      window.document.title = defaultTitle.current
+    }
+  })
+}

package/node_modules/@oneplatformdev/hooks/src/useEventCallback/index.ts

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

package/node_modules/@oneplatformdev/hooks/src/useEventCallback/useEventCallback.ts

@@ -0,0 +1,40 @@
+import { useCallback, useRef } from 'react'
+
+import { useIsomorphicLayoutEffect } from '../useIsomorphicLayoutEffect'
+
+/**
+ * Custom hook that creates a memoized event callback.
+ * @template Args - An array of argument types for the event callback.
+ * @template R - The return type of the event callback.
+ * @param {(...args: Args) => R} fn - The callback function.
+ * @returns {(...args: Args) => R} A memoized event callback function.
+ * @public
+ * @see [Documentation](https://usehooks-ts.com/react-hook/use-event-callback)
+ * @example
+ * ```tsx
+ * const handleClick = useEventCallback((event) => {
+ *   // Handle the event here
+ * });
+ * ```
+ */
+export function useEventCallback<Args extends unknown[], R>(
+  fn: (...args: Args) => R,
+): (...args: Args) => R
+export function useEventCallback<Args extends unknown[], R>(
+  fn: ((...args: Args) => R) | undefined,
+): ((...args: Args) => R) | undefined
+export function useEventCallback<Args extends unknown[], R>(
+  fn: ((...args: Args) => R) | undefined,
+): ((...args: Args) => R) | undefined {
+  const ref = useRef<typeof fn>(() => {
+    throw new Error('Cannot call an event handler while rendering.')
+  })
+
+  useIsomorphicLayoutEffect(() => {
+    ref.current = fn
+  }, [fn])
+
+  return useCallback((...args: Args) => ref.current?.(...args), [ref]) as (
+    ...args: Args
+  ) => R
+}

package/node_modules/@oneplatformdev/hooks/src/useEventListener/index.ts

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

package/node_modules/@oneplatformdev/hooks/src/useEventListener/useEventListener.ts

@@ -0,0 +1,121 @@
+import { useEffect, useRef } from 'react'
+
+import type { RefObject } from 'react'
+
+import { useIsomorphicLayoutEffect } from '../useIsomorphicLayoutEffect/useIsomorphicLayoutEffect'
+
+// MediaQueryList Event based useEventListener interface
+function useEventListener<K extends keyof MediaQueryListEventMap>(
+  eventName: K,
+  handler: (event: MediaQueryListEventMap[K]) => void,
+  element: RefObject<MediaQueryList>,
+  options?: boolean | AddEventListenerOptions,
+): void
+
+// Window Event based useEventListener interface
+function useEventListener<K extends keyof WindowEventMap>(
+  eventName: K,
+  handler: (event: WindowEventMap[K]) => void,
+  element?: undefined,
+  options?: boolean | AddEventListenerOptions,
+): void
+
+// Element Event based useEventListener interface
+function useEventListener<
+  K extends keyof HTMLElementEventMap & keyof SVGElementEventMap,
+  T extends Element = K extends keyof HTMLElementEventMap
+    ? HTMLDivElement
+    : SVGElement,
+>(
+  eventName: K,
+  handler:
+    | ((event: HTMLElementEventMap[K]) => void)
+    | ((event: SVGElementEventMap[K]) => void),
+  element: RefObject<T>,
+  options?: boolean | AddEventListenerOptions,
+): void
+
+// Document Event based useEventListener interface
+function useEventListener<K extends keyof DocumentEventMap>(
+  eventName: K,
+  handler: (event: DocumentEventMap[K]) => void,
+  element: RefObject<Document>,
+  options?: boolean | AddEventListenerOptions,
+): void
+
+/**
+ * Custom hook that attaches event listeners to DOM elements, the window, or media query lists.
+ * @template KW - The type of event for window events.
+ * @template KH - The type of event for HTML or SVG element events.
+ * @template KM - The type of event for media query list events.
+ * @template T - The type of the DOM element (default is `HTMLElement`).
+ * @param {KW | KH | KM} eventName - The name of the event to listen for.
+ * @param {(event: WindowEventMap[KW] | HTMLElementEventMap[KH] | SVGElementEventMap[KH] | MediaQueryListEventMap[KM] | Event) => void} handler - The event handler function.
+ * @param {RefObject<T>} [element] - The DOM element or media query list to attach the event listener to (optional).
+ * @param {boolean | AddEventListenerOptions} [options] - An options object that specifies characteristics about the event listener (optional).
+ * @public
+ * @see [Documentation](https://usehooks-ts.com/react-hook/use-event-listener)
+ * @example
+ * ```tsx
+ * // Example 1: Attach a window event listener
+ * useEventListener('resize', handleResize);
+ * ```
+ * @example
+ * ```tsx
+ * // Example 2: Attach a document event listener with options
+ * const elementRef = useRef(document);
+ * useEventListener('click', handleClick, elementRef, { capture: true });
+ * ```
+ * @example
+ * ```tsx
+ * // Example 3: Attach an element event listener
+ * const buttonRef = useRef<HTMLButtonElement>(null);
+ * useEventListener('click', handleButtonClick, buttonRef);
+ * ```
+ */
+function useEventListener<
+  KW extends keyof WindowEventMap,
+  KH extends keyof HTMLElementEventMap & keyof SVGElementEventMap,
+  KM extends keyof MediaQueryListEventMap,
+  T extends HTMLElement | SVGAElement | MediaQueryList = HTMLElement,
+>(
+  eventName: KW | KH | KM,
+  handler: (
+    event:
+      | WindowEventMap[KW]
+      | HTMLElementEventMap[KH]
+      | SVGElementEventMap[KH]
+      | MediaQueryListEventMap[KM]
+      | Event,
+  ) => void,
+  element?: RefObject<T>,
+  options?: boolean | AddEventListenerOptions,
+) {
+  // Create a ref that stores handler
+  const savedHandler = useRef(handler)
+
+  useIsomorphicLayoutEffect(() => {
+    savedHandler.current = handler
+  }, [handler])
+
+  useEffect(() => {
+    // Define the listening target
+    const targetElement: T | Window = element?.current ?? window
+
+    if (!(targetElement && targetElement.addEventListener)) return
+
+    // Create event listener that calls handler function stored in ref
+    const listener: typeof handler = event => {
+      savedHandler.current(event)
+    }
+
+    targetElement.addEventListener(eventName, listener, options)
+
+    // Remove event listener on cleanup
+    return () => {
+      targetElement.removeEventListener(eventName, listener, options)
+    }
+  }, [eventName, element, options])
+}
+
+export { useEventListener }

package/node_modules/@oneplatformdev/hooks/src/useHover/index.ts

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

package/node_modules/@oneplatformdev/hooks/src/useHover/useHover.ts

@@ -0,0 +1,37 @@
+import { useState } from 'react'
+
+import type { RefObject } from 'react'
+
+import { useEventListener } from '../useEventListener'
+
+/**
+ * Custom hook that tracks whether a DOM element is being hovered over.
+ * @template T - The type of the DOM element. Defaults to `HTMLElement`.
+ * @param {RefObject<T>} elementRef - The ref object for the DOM element to track.
+ * @returns {boolean} A boolean value indicating whether the element is being hovered over.
+ * @public
+ * @see [Documentation](https://usehooks-ts.com/react-hook/use-hover)
+ * @example
+ * ```tsx
+ * const buttonRef = useRef<HTMLButtonElement>(null);
+ * const isHovered = useHover(buttonRef);
+ * // Access the isHovered variable to determine if the button is being hovered over.
+ * ```
+ */
+export function useHover<T extends HTMLElement = HTMLElement>(
+  elementRef: RefObject<T>,
+): boolean {
+  const [value, setValue] = useState<boolean>(false)
+
+  const handleMouseEnter = () => {
+    setValue(true)
+  }
+  const handleMouseLeave = () => {
+    setValue(false)
+  }
+
+  useEventListener('mouseenter', handleMouseEnter, elementRef)
+  useEventListener('mouseleave', handleMouseLeave, elementRef)
+
+  return value
+}

package/node_modules/@oneplatformdev/hooks/src/useIntersectionObserver/index.ts

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