@julseb-lib/react 0.1.2 → 0.1.4

package/src/lib/components/Tooltip/__preview__/Tooltip.preview.tsx

@@ -0,0 +1,117 @@
+import { Tooltip, Text } from "../../../"
+import type { ILibTooltip } from "../../../types/components-props"
+import type { ComponentPreview } from "../../../../data/components"
+
+export const tooltipPreview: ComponentPreview<ILibTooltip> = {
+	name: "Tooltip",
+	component: Tooltip,
+	category: "components",
+	import: "Tooltip",
+	additionalImports: null,
+	optionalImports: null,
+	propsImport: "ILibTooltip",
+	additionalTypeImports: null,
+	extends: ["HTMLDivElement"],
+	previews: [
+		{
+			previewTitle: "Click",
+			props: {
+				tooltip: "Hello World!",
+				trigger: "click",
+				children: <Text>Hello, trigger on click</Text>,
+			},
+		},
+		{
+			previewTitle: "Hover",
+			props: {
+				tooltip: "Hello World!",
+				trigger: "hover",
+				hideArrow: true,
+				position: "bottom",
+				children: "Hello, trigger on hover without arrow",
+			},
+		},
+		{
+			previewTitle: "Left",
+			props: {
+				tooltip: "Hello World!",
+				position: "left",
+				children: "Hello tooltip left",
+			},
+		},
+		{
+			previewTitle: "Right",
+			props: {
+				tooltip: "Hello World!",
+				position: "right",
+				children: "Hello tooltip right",
+			},
+		},
+	],
+	props: [
+		{
+			name: "tooltip",
+			type: "string",
+			possibleValues: null,
+			defaultValue: null,
+			description: "The tooltip text or React element to display.",
+			isRequired: true,
+		},
+		{
+			name: "position",
+			type: "string",
+			possibleValues: ["top", "bottom", "left", "right"],
+			defaultValue: null,
+			description: "Tooltip position.",
+			isRequired: false,
+		},
+		{
+			name: "hideArrow",
+			type: "boolean",
+			possibleValues: null,
+			defaultValue: null,
+			description: "If true, hides the tooltip arrow.",
+			isRequired: false,
+		},
+		{
+			name: "trigger",
+			type: "string",
+			possibleValues: ["hover", "click"],
+			defaultValue: null,
+			description: "Tooltip trigger event.",
+			isRequired: false,
+		},
+		{
+			name: "backgroundColor",
+			type: "string",
+			possibleValues: "Any color from the library",
+			defaultValue: null,
+			description: "Tooltip background color.",
+			isRequired: false,
+		},
+		{
+			name: "textColor",
+			type: "string",
+			possibleValues: "Any color from the library",
+			defaultValue: null,
+			description: "Tooltip text color.",
+			isRequired: false,
+		},
+		{
+			name: "offset",
+			type: "string",
+			possibleValues: ["2xs", "xs", "sm", "md", "lg", "xl", "2xl", "0px"],
+			defaultValue: null,
+			description: "Tooltip offset.",
+			isRequired: false,
+		},
+		{
+			name: "tooltipClasses",
+			type: "string",
+			possibleValues: null,
+			defaultValue: null,
+			description: "Additional class names for the tooltip.",
+			isRequired: false,
+		},
+	],
+}

package/src/lib/components/Tooltip/types.ts

@@ -0,0 +1,23 @@
+import type { ReactElement } from "react"
+import type {
+	ClassNames,
+	CSSProperties,
+	LibAllColors,
+	LibAllColorsAndOverlays,
+	LibComponentBase,
+	LibSpacers,
+	LibTooltipPosition,
+	LibTooltipTrigger,
+} from "../../types"
+
+export interface ILibTooltip extends LibComponentBase<HTMLSpanElement> {
+	tooltip: string | ReactElement
+	position?: LibTooltipPosition
+	hideArrow?: boolean
+	trigger?: LibTooltipTrigger
+	backgroundColor?: LibAllColorsAndOverlays
+	textColor?: LibAllColors
+	offset?: LibSpacers
+	tooltipClasses?: ClassNames
+	tooltipStyle?: CSSProperties
+}

package/src/lib/components/Wrapper/Wrapper.tsx

@@ -0,0 +1,75 @@
+import { type FC } from "react"
+import { clsx, genBgAllColors, genGap } from "../../utils"
+import type { ILibWrapper } from "./types"
+
+/**
+ * Wrapper component for providing a responsive layout container.
+ *
+ * @component
+ * @example
+ * <Wrapper>
+ *   <Main>Content</Main>
+ * </Wrapper>
+ *
+ * @extends HTMLDivElement
+ *
+ * @prop {object} props - Component props.
+ * @prop {string} [props.className] - Additional class names to apply.
+ * @prop {ElementType} [props.element="section"] - The HTML element or React component to render as the wrapper container.
+ * @prop {RefObject<HTMLDivElement>} [props.ref] - Ref for the wrapper container.
+ * @prop {ReactNode} props.children - Wrapper content.
+ * @prop {"px"|"full"|"screen"|"dvh"|"dvw"|"lvh"|"lvw"|"svw"|"svh"|"auto"|"min"|"max"|"fit"|"lh"|} [props.minHeight="svh"] - Minimum height class (uses Tailwind min-h-* utilities).
+ * @prop {string} [props.backgroundColor="background"] - Any color from the library.
+ * @prop {"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"0px"} [props.gap="lg"] - Gap between children (uses library spacers).
+ * @prop {object} [props.rest] - Additional props spread to the container.
+ *
+ * @returns {JSX.Element} The rendered wrapper container.
+ *
+ * @see https://doc-julseb-lib-react.vercel.app/styles/wrapper
+ */
+export const Wrapper: FC<ILibWrapper> = ({
+	className,
+	element = "section",
+	children,
+	ref,
+	minHeight = "svh",
+	backgroundColor = "background",
+	gap = "lg",
+	...rest
+}) => {
+	const Element = element
+
+	return (
+		<Element
+			ref={ref}
+			className={clsx(
+				"z-10 relative flex sm:flex-row flex-col justify-stretch sm:justify-center-safe gap-6 px-4 md:px-6 lg:px-12 w-full",
+				(genBgAllColors as any)[backgroundColor],
+				genMinHeight[minHeight],
+				genGap[gap],
+				"wrapper",
+				className,
+			)}
+			{...rest}
+		>
+			{children}
+		</Element>
+	)
+}
+
+const genMinHeight = {
+	px: "min-h-px",
+	full: "min-h-full",
+	screen: "min-h-screen",
+	dvh: "min-h-dvh",
+	dvw: "min-h-dvw",
+	lvh: "min-h-lvh",
+	lvw: "min-h-lvw",
+	svw: "min-h-svw",
+	svh: "min-h-svh",
+	auto: "min-h-auto",
+	min: "min-h-min",
+	max: "min-h-max",
+	fit: "min-h-fit",
+	lh: "min-h-lh",
+}

package/src/lib/components/Wrapper/__preview__/Wrapper.preview.tsx

@@ -0,0 +1,78 @@
+import { Link } from "react-router-dom"
+import { Wrapper, Text } from "../../../"
+import type { ILibWrapper } from "../../../types/components-props"
+import type { ComponentPreview } from "../../../../data/components"
+
+export const wrapperPreview: ComponentPreview<ILibWrapper> = {
+	name: "Wrapper",
+	component: Wrapper,
+	category: "styles",
+	import: "Wrapper",
+	additionalImports: null,
+	optionalImports: null,
+	propsImport: "ILibWrapper",
+	additionalTypeImports: null,
+	extends: ["HTMLSectionElement"],
+	previews: [
+		{
+			demo: (
+				<div className="flex flex-col gap-2">
+					<Text>
+						<Link
+							to="/main/demo-default"
+							target="_blank"
+							rel="noreferrer noopener"
+						>
+							Demo main default
+						</Link>
+					</Text>
+					<Text>
+						<Link
+							to="/aside/demo-left"
+							target="_blank"
+							rel="noreferrer noopener"
+						>
+							Demo main and aside
+						</Link>
+					</Text>
+				</div>
+			),
+		},
+	],
+	props: [
+		{
+			name: "gap",
+			type: "string",
+			possibleValues: ["2xs", "xs", "sm", "md", "lg", "xl", "2xl"],
+			defaultValue: "lg",
+			description: "Spacing between children elements.",
+			isRequired: false,
+		},
+		{
+			name: "backgroundColor",
+			type: "string",
+			possibleValues: "Any color from the library",
+			defaultValue: "background",
+			description: "Background color of the wrapper.",
+			isRequired: false,
+		},
+		{
+			name: "minHeight",
+			type: "string",
+			possibleValues: [
+				"0",
+				"full",
+				"screen",
+				"min",
+				"max",
+				"fit",
+				"dvh",
+				"lvh",
+				"svh",
+			],
+			defaultValue: "svh",
+			description: "Minimum height of the wrapper.",
+			isRequired: false,
+		},
+	],
+}

package/src/lib/components/Wrapper/types.ts

@@ -0,0 +1,12 @@
+import type {
+	LibComponentBase,
+	LibSpacers,
+	LibAllColors,
+	LibMinHeight,
+} from "../../types"
+
+export interface ILibWrapper extends LibComponentBase<HTMLDivElement> {
+	gap?: LibSpacers
+	backgroundColor?: LibAllColors
+	minHeight?: LibMinHeight
+}

package/src/lib/context/Theme.context.tsx

@@ -0,0 +1,66 @@
+import { useState, useEffect, createContext, useContext } from "react"
+import type { LibThemeNames, ReactChildren, DispatchState } from "../types"
+
+type ILibThemeContext = {
+	theme: LibThemeNames
+	setTheme: DispatchState<LibThemeNames>
+	switchTheme: () => void
+}
+
+const ThemeContext = createContext<ILibThemeContext | null>(null)
+
+interface ILibThemeProvider {
+	children?: ReactChildren
+}
+
+export const ThemeProviderWrapper = ({ children }: ILibThemeProvider) => {
+	const storedTheme = localStorage.getItem("theme") as LibThemeNames
+	const [theme, setTheme] = useState(storedTheme ?? "light")
+
+	const docEl = document.documentElement
+
+	const switchToLight = () => {
+		docEl.classList.add("light")
+		docEl.classList.remove("dark")
+		setTheme("light")
+		localStorage.setItem("theme", "light")
+	}
+
+	const switchToDark = () => {
+		docEl.classList.remove("light")
+		docEl.classList.add("dark")
+		setTheme("dark")
+		localStorage.setItem("theme", "dark")
+	}
+
+	useEffect(() => {
+		if (storedTheme) {
+			if (theme === "light") switchToLight()
+			else switchToDark()
+		} else {
+			if (window.matchMedia("(prefers-color-scheme: dark)").matches)
+				switchToDark()
+			else switchToLight()
+		}
+	}, [theme, localStorage.getItem("theme"), docEl])
+
+	const switchTheme = () => {
+		if (theme === "light") switchToDark()
+		else switchToLight()
+	}
+
+	return (
+		<ThemeContext.Provider value={{ theme, setTheme, switchTheme }}>
+			{children}
+		</ThemeContext.Provider>
+	)
+}
+
+/**
+ * Custom hook to access the theme context.
+ *
+ * @returns {ILibThemeContext} The current theme, a setter for the theme, and a function to toggle between light and dark themes.
+ * @example
+ * const { theme, setTheme, switchTheme } = useLibTheme()
+ */
+export const useLibTheme = () => useContext(ThemeContext) as ILibThemeContext

package/src/lib/context/index.ts

@@ -0,0 +1 @@
+export * from "./Theme.context"

package/src/lib/hooks/useClickOutside.tsx

@@ -0,0 +1,50 @@
+import { useEffect, type RefObject } from "react"
+
+type Event = MouseEvent | TouchEvent
+
+/**
+ * Hook to trigger a function when clicking outside a referenced element.
+ *
+ * @hook
+ *
+ * @example
+ * const ref = useRef<HTMLDivElement>(null)
+ * useClickOutside(ref, () => {
+ *   console.log('Clicked outside!')
+ *   setIsOpen(false)
+ * })
+ *
+ * @template T - HTML element type that extends HTMLElement
+ * @param {RefObject<T>} ref - React ref object pointing to the target element
+ * @param {function} handler - Callback function to execute when clicking outside the element
+ * @param {Event} handler.event - The mouse or touch event that triggered the outside click
+ *
+ * @returns {void} This hook doesn't return anything
+ *
+ * @see https://doc-julseb-lib-react.vercel.app/helpers/hooks#useClickOutside
+ */
+export const useClickOutside = <T extends HTMLElement = HTMLElement>(
+	ref: RefObject<T>,
+	handler: (event: Event) => void,
+) => {
+	useEffect(() => {
+		const listener = (e: Event) => {
+			const target = e.target as HTMLElement
+
+			if (target.getAttribute("href")) return false
+
+			const el = ref?.current
+			if (!el || el.contains((e?.target as Node) || null)) {
+				return
+			}
+
+			handler(e)
+		}
+
+		document.addEventListener("mousedown", listener)
+
+		return () => {
+			document.removeEventListener("mousedown", listener)
+		}
+	}, [ref, handler])
+}

package/src/lib/hooks/useCopyToClipboard.tsx

@@ -0,0 +1,50 @@
+import { useState } from "react"
+
+type CopiedValue = string | null
+type CopyFn = (text: string) => Promise<boolean>
+
+/**
+ * Hook to copy text to clipboard and track the copied value state.
+ *
+ * @hook
+ *
+ * @example
+ * const [copiedText, copy] = useCopyToClipboard()
+ *
+ * const handleCopy = async () => {
+ *   const success = await copy('Hello, World!')
+ *   if (success) {
+ *     console.log('Copied:', copiedText)
+ *   }
+ * }
+ *
+ * @returns {[CopiedValue, CopyFn]} Array containing the last copied text and copy function
+ * @returns {string | null} returns[0] - The last successfully copied text, or null if no text copied or copy failed
+ * @returns {function} returns[1] - Async function to copy text to clipboard
+ * @returns {string} returns[1].text - Text to copy to clipboard
+ * @returns {Promise<boolean>} returns[1].Promise - Promise that resolves to true if copy succeeded, false otherwise
+ *
+ * @see https://doc-julseb-lib-react.vercel.app/helpers/hooks#useCopyToClipboard
+ */
+export const useCopyToClipboard = (): [CopiedValue, CopyFn] => {
+	const [copiedText, setCopiedText] = useState<CopiedValue>(null)
+
+	const copy: CopyFn = async text => {
+		if (!navigator?.clipboard) {
+			console.warn("Clipboard not supported")
+			return false
+		}
+
+		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/lib/hooks/useDebounce.tsx

@@ -0,0 +1,37 @@
+import { useState, useEffect } from "react"
+
+/**
+ * Hook to delay the update of a value until after a specified delay period has passed without changes.
+ *
+ * @hook
+ *
+ * @example
+ * const [searchTerm, setSearchTerm] = useState('')
+ * const debouncedSearchTerm = useDebounce(searchTerm, 500)
+ *
+ * useEffect(() => {
+ *   if (debouncedSearchTerm) {
+ *     // Perform search API call
+ *     searchAPI(debouncedSearchTerm)
+ *   }
+ * }, [debouncedSearchTerm])
+ *
+ * @template T - Type of the value being debounced
+ * @param {T} value - The value to debounce
+ * @param {number} [delay=1000] - Delay in milliseconds before updating the debounced value
+ *
+ * @returns {T} The debounced value that updates after the delay period
+ *
+ * @see https://doc-julseb-lib-react.vercel.app/helpers/hooks#useDebounce
+ */
+export const useDebounce = <T,>(value: T, delay: number = 1000) => {
+	const [debouncedValue, setDebouncedValue] = useState<T>(value)
+
+	useEffect(() => {
+		const timedValue = setTimeout(() => setDebouncedValue(value), delay)
+
+		return () => clearTimeout(timedValue)
+	}, [value, delay])
+
+	return debouncedValue
+}

package/src/lib/hooks/useExportData.tsx

@@ -0,0 +1,78 @@
+interface IDownloadFile {
+	blob: Blob
+	fileName: string
+}
+
+const downloadFile = ({ blob, fileName }: IDownloadFile) => {
+	const a = document.createElement("a")
+	a.download = fileName
+	a.href = window.URL.createObjectURL(blob)
+	const clickEvt = new MouseEvent("click", {
+		view: window,
+		bubbles: true,
+		cancelable: true,
+	})
+	a.dispatchEvent(clickEvt)
+	a.remove()
+}
+
+/**
+ * Hook to export data to JSON or CSV format with automatic file download functionality.
+ *
+ * @hook
+ *
+ * @example
+ * const { exportToJson, exportToCsv } = useExportData()
+ *
+ * // Export to JSON
+ * const users = [{ id: 1, name: 'John' }, { id: 2, name: 'Jane' }]
+ * exportToJson(users, 'users-data')
+ *
+ * // Export to CSV
+ * const headers = ['ID', 'Name']
+ * exportToCsv(users, 'users-data', headers)
+ *
+ * @template T - Type of the data objects being exported
+ *
+ * @returns {object} Object containing export functions
+ * @returns {function} returns.exportToJson - Function to export data as JSON file
+ * @returns {Array<T>} returns.exportToJson.data - Array of data objects to export
+ * @returns {string} returns.exportToJson.fileName - Name for the downloaded file (without extension)
+ * @returns {function} returns.exportToCsv - Function to export data as CSV file
+ * @returns {Array<T>} returns.exportToCsv.data - Array of data objects to export
+ * @returns {string} returns.exportToCsv.fileName - Name for the downloaded file (without extension)
+ * @returns {Array<string>} returns.exportToCsv.headers - Array of column headers for the CSV file
+ *
+ * @see https://doc-julseb-lib-react.vercel.app/helpers/hooks#useExportData
+ */
+export const useExportData = <T,>() => {
+	const exportToJson = (data: Array<T>, fileName: string) =>
+		downloadFile({
+			blob: new Blob([JSON.stringify(data)], {
+				type: "application/json",
+			}),
+			fileName: `${fileName}.json`,
+		})
+
+	const exportToCsv = (
+		data: Array<T>,
+		fileName: string,
+		headers: Array<string>,
+	) => {
+		const rows = [headers.join(","), ...data].join("\n")
+
+		const blob = new Blob([rows], {
+			type: "text/csv",
+		})
+
+		return downloadFile({
+			blob,
+			fileName: `${fileName}.csv`,
+		})
+	}
+
+	return {
+		exportToCsv,
+		exportToJson,
+	}
+}

package/src/lib/hooks/useFetch.tsx

@@ -0,0 +1,42 @@
+import { useEffect, useState } from "react"
+
+/**
+ * Hook to fetch data from a Promise with loading and error state management.
+ *
+ * @hook
+ *
+ * @example
+ * const { response, error, loading } = useFetch(
+ *   fetch('/api/users').then(res => res.json()),
+ *   [userId]
+ * )
+ *
+ * if (loading) return <div>Loading...</div>
+ * if (error) return <div>Error: {error.message}</div>
+ * return <div>{response?.name}</div>
+ *
+ * @template T - Type of the data returned by the fetch function
+ * @param {Promise<T>} fetchFunction - Promise that resolves to the data to be fetched
+ * @param {any} [dependencies] - Dependency array to trigger re-fetching when values change
+ *
+ * @returns {object} Object containing fetch state
+ * @returns {T | null} returns.response - The fetched data, or null if not yet loaded or failed
+ * @returns {any} returns.error - Error object if the fetch failed, undefined otherwise
+ * @returns {boolean} returns.loading - Whether the fetch operation is currently in progress
+ *
+ * @see https://doc-julseb-lib-react.vercel.app/helpers/hooks#useFetch
+ */
+export const useFetch = <T,>(fetchFunction: Promise<T>, dependencies?: any) => {
+	const [response, setResponse] = useState<T | null>(null)
+	const [loading, setLoading] = useState(true)
+	const [error, setError] = useState<any>(undefined)
+
+	useEffect(() => {
+		fetchFunction
+			.then((res: T) => setResponse(res))
+			.catch((err: any) => setError(err))
+			.finally(() => setLoading(false))
+	}, [dependencies])
+
+	return { response, error, loading } as const
+}

package/src/lib/hooks/useForm.tsx

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