@julseb-lib/react 0.1.19 → 0.1.20

package/dist/lib/hooks/useForm.tsx

@@ -1,51 +0,0 @@
-import { useState, type ChangeEvent } from "react"
-
-/**
- * Hook to manage form state with input handling, validation, and submission functionality.
- *
- * @hook
- *
- * @example
- * interface FormData {
- *   email: string
- *   password: string
- * }
- *
- * const { formData, handleInputs, resetForm, handleSubmit } = useForm<FormData>(
- *   { email: '', password: '' },
- *   (data) => console.log('Form submitted:', data)
- * )
- *
- * @template T - Type of the form data object
- * @param {T} [initialState={}] - Initial state of the form data
- * @param {function} [onSubmit] - Optional callback function called on form submission
- * @param {T} onSubmit.formData - The current form data when submitted
- *
- * @returns {object} Object containing form state and handlers
- * @returns {T} returns.formData - Current form data state
- * @returns {function} returns.handleInputs - Function to handle input changes
- * @returns {ChangeEvent<HTMLInputElement>} returns.handleInputs.e - Input change event
- * @returns {function} returns.resetForm - Function to reset form to initial state
- * @returns {function} returns.handleSubmit - Function to handle form submission
- * @returns {ChangeEvent<HTMLFormElement>} returns.handleSubmit.e - Form submit event
- *
- * @see https://doc-julseb-lib-react.vercel.app/helpers/hooks#useForm
- */
-export const useForm = <T,>(
-	initialState = {} as T,
-	onSubmit?: (formData: T) => void,
-) => {
-	const [formData, setFormData] = useState(initialState)
-
-	const handleInputs = (e: ChangeEvent<HTMLInputElement>) =>
-		setFormData({ ...formData, [e.target.id]: e.target.value })
-
-	const resetForm = () => setFormData(initialState)
-
-	const handleSubmit = (e: ChangeEvent<HTMLFormElement>) => {
-		e.preventDefault()
-		onSubmit?.(formData)
-	}
-
-	return { formData, handleInputs, resetForm, handleSubmit }
-}

package/dist/lib/hooks/useIsOverflow.ts

@@ -1,61 +0,0 @@
-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/dist/lib/hooks/useKeyPress.tsx

@@ -1,110 +0,0 @@
-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/dist/lib/hooks/useMaxWidth.tsx

@@ -1,40 +0,0 @@
-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/dist/lib/hooks/useMergeRefs.ts

@@ -1,45 +0,0 @@
-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/dist/lib/hooks/useMinWidth.tsx

@@ -1,40 +0,0 @@
-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/dist/lib/hooks/usePaginatedData.tsx

@@ -1,52 +0,0 @@
-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/dist/lib/hooks/usePagination.tsx

@@ -1,75 +0,0 @@
-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/dist/lib/hooks/useTouchScreen.tsx

@@ -1,34 +0,0 @@
-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/dist/lib/hooks/useTranslation.tsx

@@ -1,58 +0,0 @@
-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,
-	}
-}