@julseb-lib/react 0.1.3 → 0.1.4

package/src/lib/hooks/useIsOverflow.ts

@@ -0,0 +1,61 @@
+import {
+	useState,
+	useLayoutEffect,
+	type RefCallback,
+	type RefObject,
+} from "react"
+
+/**
+ * Hook to detect if an element is overflowing its container bounds with optional callback functionality.
+ *
+ * @hook
+ *
+ * @example
+ * const ref = useRef<HTMLDivElement>(null)
+ * const isOverflow = useIsOverflow(ref, {
+ *   callback: (overflow) => console.log('Overflow detected:', overflow),
+ *   check: 'width'
+ * })
+ *
+ * if (isOverflow) {
+ *   // Handle overflow state
+ * }
+ *
+ * @param {RefObject<HTMLElement>} ref - React ref object pointing to the element to check for overflow
+ * @param {object} [options] - Configuration options for overflow detection
+ * @param {RefCallback<boolean>} [options.callback] - Callback function called when overflow state changes
+ * @param {"width" | "height"} [options.check="width"] - Which dimension to check for overflow
+ *
+ * @returns {boolean | undefined} Whether the element is overflowing, or undefined if not yet determined
+ *
+ * @see https://doc-julseb-lib-react.vercel.app/helpers/hooks#useIsOverflow
+ */
+export const useIsOverflow = (
+	ref: RefObject<HTMLElement>,
+	options?: {
+		callback: RefCallback<boolean>
+		check?: "width" | "height"
+	},
+) => {
+	const [isOverflow, setIsOverflow] = useState<undefined | boolean>(undefined)
+
+	useLayoutEffect(() => {
+		const { current } = ref
+
+		const trigger = () => {
+			if (current) {
+				const hasOverflow =
+					options?.check === "height"
+						? current.scrollHeight > current.clientHeight
+						: current.scrollWidth > current.clientWidth
+				setIsOverflow(hasOverflow)
+
+				if (options?.callback) options.callback(hasOverflow)
+			}
+		}
+
+		trigger()
+	}, [ref, options])
+
+	return isOverflow
+}

package/src/lib/hooks/useKeyPress.tsx

@@ -0,0 +1,110 @@
+import { useEffect } from "react"
+
+/**
+ * Hook to trigger functions on specific key press events with support for modifier keys and exclusions.
+ *
+ * @hook
+ *
+ * @example
+ * // Single key press
+ * useKeyPress('Escape', () => setIsOpen(false))
+ *
+ * // Modifier key combination
+ * useKeyPress(['Control', 'KeyS'], () => saveDocument())
+ *
+ * // With excluded keys
+ * useKeyPress('Enter', handleSubmit, ['Shift'])
+ *
+ * @param {string | Array<string>} keyCodes - Single key code or array of key codes for combinations
+ * @param {function} callback - Function to execute when the key combination is pressed
+ * @param {Array<string>} [excludeKeys] - Array of modifier keys to exclude from triggering the callback
+ *
+ * @returns {void} This hook doesn't return anything
+ *
+ * @see https://doc-julseb-lib-react.vercel.app/helpers/hooks#useKeyPress
+ */
+export const useKeyPress = (
+	keyCodes: string | Array<string>,
+	callback: () => void,
+	excludeKeys?: Array<string>,
+): void => {
+	useEffect(() => {
+		const singleHandler = ({ code }: KeyboardEvent) => {
+			if (keyCodes.includes(code)) {
+				callback()
+			}
+		}
+
+		const multiHandler = (e: KeyboardEvent) => {
+			if (typeof keyCodes !== "string") {
+				const metaKey =
+					keyCodes[0] === "Command" ? e.metaKey : undefined
+				const ctrlKey =
+					keyCodes[0] === "Control" ? e.ctrlKey : undefined
+				const shiftKey =
+					keyCodes[0] === "Shift" ? e.shiftKey : undefined
+				const altKey = keyCodes[0] === "Alt" ? e.altKey : undefined
+
+				const excludedMetaKey =
+					excludeKeys && excludeKeys[0] === "Command"
+						? e.metaKey
+						: undefined
+				const excludedCtrlKey =
+					excludeKeys && excludeKeys[0] === "Control"
+						? e.ctrlKey
+						: undefined
+				const excludedShiftKey =
+					excludeKeys && excludeKeys[0] === "Shift"
+						? e.shiftKey
+						: undefined
+				const excludedAltKey =
+					excludeKeys && excludeKeys[0] === "Alt"
+						? e.altKey
+						: undefined
+
+				if (
+					keyCodes.length === 1 &&
+					!(
+						excludedMetaKey ||
+						excludedCtrlKey ||
+						excludedShiftKey ||
+						excludedAltKey
+					)
+				) {
+					singleHandler(e)
+				}
+
+				if (
+					excludedMetaKey ||
+					excludedCtrlKey ||
+					excludedShiftKey ||
+					excludedAltKey
+				) {
+					return
+				}
+
+				if (
+					(metaKey || ctrlKey || shiftKey || altKey) &&
+					e.code === keyCodes[1]
+				) {
+					callback()
+				}
+			}
+		}
+
+		window.addEventListener(
+			"keydown",
+			typeof keyCodes !== "string" || (keyCodes && excludeKeys)
+				? multiHandler
+				: singleHandler,
+		)
+
+		return () =>
+			window.removeEventListener(
+				"keydown",
+				typeof keyCodes !== "string" && keyCodes.length > 1
+					? multiHandler
+					: singleHandler,
+			)
+	}, [callback, keyCodes])
+}

package/src/lib/hooks/useMaxWidth.tsx

@@ -0,0 +1,40 @@
+import { useState, useEffect } from "react"
+
+/**
+ * Hook to detect if the viewport width is smaller than or equal to a specified width breakpoint.
+ *
+ * @hook
+ *
+ * @example
+ * const isMobile = useMaxWidth(768)
+ * const isTablet = useMaxWidth(1024)
+ *
+ * if (isMobile) {
+ *   // Render mobile layout
+ * }
+ *
+ * @param {number} width - The maximum width breakpoint to check against
+ *
+ * @returns {boolean} Whether the current viewport width is smaller than or equal to the specified width
+ *
+ * @see https://doc-julseb-lib-react.vercel.app/helpers/hooks#useMaxWidth
+ */
+export const useMaxWidth = (width: number): boolean => {
+	const [isMax, setIsMax] = useState<boolean>(false)
+
+	useEffect(() => {
+		const detectSize = () => {
+			if (window.innerWidth <= width) {
+				setIsMax(true)
+			} else {
+				setIsMax(false)
+			}
+		}
+
+		detectSize()
+
+		window.addEventListener("resize", () => detectSize())
+	}, [width])
+
+	return isMax
+}

package/src/lib/hooks/useMergeRefs.ts

@@ -0,0 +1,45 @@
+import {
+	useMemo,
+	type Ref,
+	type RefCallback,
+	type MutableRefObject,
+} from "react"
+
+/**
+ * Hook to merge multiple refs into a single ref callback for use on a single element.
+ *
+ * @hook
+ *
+ * @example
+ * const ref1 = useRef<HTMLDivElement>(null)
+ * const ref2 = useRef<HTMLDivElement>(null)
+ * const mergedRef = useMergeRefs([ref1, ref2])
+ *
+ * return <div ref={mergedRef}>Content</div>
+ *
+ * @template Instance - Type of the element instance being referenced
+ * @param {Array<Ref<Instance> | undefined>} refs - Array of refs to merge together
+ *
+ * @returns {RefCallback<Instance> | null} Merged ref callback or null if all refs are null/undefined
+ *
+ * @see https://doc-julseb-lib-react.vercel.app/helpers/hooks#useMergeRefs
+ */
+export const useMergeRefs = <Instance>(
+	refs: Array<Ref<Instance> | undefined>,
+): RefCallback<Instance> | null => {
+	return useMemo(() => {
+		if (refs.every(ref => ref == null)) {
+			return null
+		}
+
+		return value => {
+			refs.forEach(ref => {
+				if (typeof ref === "function") {
+					ref(value)
+				} else if (ref != null) {
+					;(ref as MutableRefObject<Instance | null>).current = value
+				}
+			})
+		}
+	}, refs)
+}

package/src/lib/hooks/useMinWidth.tsx

@@ -0,0 +1,40 @@
+import { useState, useEffect } from "react"
+
+/**
+ * Hook to detect if the viewport width is greater than or equal to a specified width breakpoint.
+ *
+ * @hook
+ *
+ * @example
+ * const isDesktop = useMinWidth(1024)
+ * const isTablet = useMinWidth(768)
+ *
+ * if (isDesktop) {
+ *   // Render desktop layout
+ * }
+ *
+ * @param {number} width - The minimum width breakpoint to check against
+ *
+ * @returns {boolean} Whether the current viewport width is greater than or equal to the specified width
+ *
+ * @see https://doc-julseb-lib-react.vercel.app/helpers/hooks#useMinWidth
+ */
+export const useMinWidth = (width: number): boolean => {
+	const [isMin, setIsMin] = useState<boolean>(false)
+
+	useEffect(() => {
+		const detectSize = () => {
+			if (window.innerWidth >= width) {
+				setIsMin(true)
+			} else {
+				setIsMin(false)
+			}
+		}
+
+		detectSize()
+
+		window.addEventListener("resize", () => detectSize())
+	}, [width])
+
+	return isMin
+}

package/src/lib/hooks/usePaginatedData.tsx

@@ -0,0 +1,52 @@
+interface IUsePaginatedData<T> {
+	paginatedData: Array<T>
+	totalPages: number
+}
+
+/**
+ * Hook to paginate data with URL parameter integration for use with Pagination or Paginator components.
+ *
+ * @hook
+ *
+ * @example
+ * const users = [{ id: 1, name: 'John' }, { id: 2, name: 'Jane' }, ...]
+ * const { paginatedData, totalPages } = usePaginatedData(users, 1, 10)
+ *
+ * return (
+ *   <div>
+ *     {paginatedData.map(user => <UserCard key={user.id} user={user} />)}
+ *     <Pagination totalPages={totalPages} />
+ *   </div>
+ * )
+ *
+ * @template T - Type of the data items being paginated
+ * @param {Array<T>} data - Array of data to paginate
+ * @param {number} page - Current page number (1-indexed)
+ * @param {number} [defaultLimit=20] - Number of items per page
+ *
+ * @returns {object} Object containing paginated data and pagination info
+ * @returns {Array<T>} returns.paginatedData - Current page's data items
+ * @returns {number} returns.totalPages - Total number of pages based on data length and limit
+ *
+ * @see https://doc-julseb-lib-react.vercel.app/helpers/hooks#usePaginatedData
+ */
+export const usePaginatedData = <T,>(
+	data: Array<T>,
+	page: number,
+	defaultLimit = 20,
+): IUsePaginatedData<T> => {
+	const currentPage: number = page ?? 1
+
+	const getPaginatedData = () => {
+		const startIndex = currentPage * defaultLimit - defaultLimit
+		const endIndex = startIndex + defaultLimit
+		return data?.slice(startIndex, endIndex)
+	}
+
+	const getNumberOfPages = () => Math.ceil((data?.length || 0) / defaultLimit)
+
+	return {
+		paginatedData: getPaginatedData(),
+		totalPages: getNumberOfPages(),
+	}
+}

package/src/lib/hooks/usePagination.tsx

@@ -0,0 +1,75 @@
+import { scrollToTop } from "@julseb-lib/utils"
+import type { DispatchState } from "../types"
+
+interface ILibUsePaginationNavigation {
+	currentPage: number
+	setCurrentPage: DispatchState<number>
+	totalPages?: number
+}
+
+/**
+ * Hook to manage pagination navigation with URL parameter integration and automatic scrolling.
+ *
+ * @hook
+ *
+ * @example
+ * const [currentPage, setCurrentPage] = useState(1)
+ * const { handlePrev, handleNext, handlePage } = usePagination({
+ *   currentPage,
+ *   setCurrentPage,
+ *   totalPages: 10
+ * })
+ *
+ * return (
+ *   <div>
+ *     <button onClick={handlePrev}>Previous</button>
+ *     <button onClick={() => handlePage(5)}>Go to page 5</button>
+ *     <button onClick={handleNext}>Next</button>
+ *   </div>
+ * )
+ *
+ * @param {object} params - Configuration object for pagination
+ * @param {number} params.currentPage - Current active page number
+ * @param {DispatchState<number>} params.setCurrentPage - State setter function for current page
+ * @param {number} [params.totalPages] - Total number of pages available
+ *
+ * @returns {object} Object containing pagination navigation functions
+ * @returns {function} returns.handlePrev - Function to navigate to the previous page
+ * @returns {function} returns.handleNext - Function to navigate to the next page
+ * @returns {function} returns.handlePage - Function to navigate to a specific page number
+ * @returns {number} returns.handlePage.n - Page number to navigate to
+ *
+ * @see https://doc-julseb-lib-react.vercel.app/helpers/hooks#usePagination
+ */
+export const usePagination = ({
+	currentPage,
+	setCurrentPage,
+	totalPages,
+}: ILibUsePaginationNavigation) => {
+	const handlePrev = () => {
+		setCurrentPage(currentPage - 1)
+		scrollToTop()
+	}
+
+	const handleNext = () => {
+		setCurrentPage(currentPage + 1)
+		scrollToTop()
+	}
+
+	const handlePage = (n: number) => {
+		if (n < 1) {
+			setCurrentPage(1)
+			return
+		}
+
+		if (totalPages && n > totalPages) {
+			setCurrentPage(totalPages)
+			return
+		}
+
+		setCurrentPage(n)
+		scrollToTop()
+	}
+
+	return { handlePrev, handleNext, handlePage }
+}

package/src/lib/hooks/useTouchScreen.tsx

@@ -0,0 +1,34 @@
+import { useState, useLayoutEffect } from "react"
+
+/**
+ * Hook to detect if the current device supports touch screen interaction.
+ *
+ * @hook
+ *
+ * @example
+ * const isTouchScreen = useTouchScreen()
+ *
+ * if (isTouchScreen) {
+ *   // Render touch-optimized UI
+ *   return <TouchOptimizedComponent />
+ * }
+ *
+ * return <DesktopComponent />
+ *
+ * @returns {boolean} Whether the current device supports touch screen interaction
+ *
+ * @see https://doc-julseb-lib-react.vercel.app/helpers/hooks#useTouchScreen
+ */
+export const useTouchScreen = (): boolean => {
+	const [isTouchScreen, setIsTouchScreen] = useState<boolean>(false)
+
+	useLayoutEffect(() => {
+		const isTouchDevice = () => {
+			return "ontouchstart" in window || navigator.maxTouchPoints > 0
+		}
+
+		setIsTouchScreen(isTouchDevice())
+	}, [])
+
+	return isTouchScreen
+}

package/src/lib/hooks/useTranslation.tsx

@@ -0,0 +1,58 @@
+import { useState, useEffect } from "react"
+import { detectLanguage } from "@julseb-lib/utils"
+import type { TranslateLang } from "../types"
+
+let currentLanguage = detectLanguage() || "en"
+
+/**
+ * Hook to detect the language and return translated content with language switching functionality.
+ *
+ * @hook
+ *
+ * @example
+ * const translations = {
+ *   en: { greeting: 'Hello', goodbye: 'Goodbye' },
+ *   fr: { greeting: 'Bonjour', goodbye: 'Au revoir' },
+ *   es: { greeting: 'Hola', goodbye: 'Adiós' }
+ * }
+ *
+ * const { translate, setLanguage, language, languages } = useTranslation(translations)
+ *
+ * return (
+ *   <div>
+ *     <p>{translate('greeting')}</p>
+ *     <button onClick={() => setLanguage('fr')}>Switch to French</button>
+ *   </div>
+ * )
+ *
+ * @param {TranslateLang} translations - Object containing translations for each language
+ * @param {object} translations[language] - Translation object for a specific language
+ * @param {string} translations[language][key] - Translated string for a specific key
+ *
+ * @returns {object} Object containing translation utilities
+ * @returns {function} returns.translate - Function to get translated text for a given key
+ * @returns {string} returns.translate.key - Translation key to look up
+ * @returns {function} returns.setLanguage - Function to change the current language
+ * @returns {string} returns.setLanguage.lang - Language code to switch to
+ * @returns {string} returns.language - Current active language code
+ * @returns {Array<string>} returns.languages - Array of available language codes
+ *
+ * @see https://doc-julseb-lib-react.vercel.app/helpers/hooks#useTranslation
+ */
+export const useTranslation = (translations: TranslateLang) => {
+	const [language, setLanguage] = useState<string>(currentLanguage)
+	const languages = Object.keys(translations)
+
+	useEffect(() => {
+		currentLanguage = language || "en"
+	}, [language])
+
+	const translate = (key: string) => translations?.[language]?.[key]
+
+	return {
+		translate,
+		setLanguage,
+		language,
+		languages,
+	}
+}