@tarsis/toolkit 0.6.5 → 0.7.0

package/dist/hooks.js

@@ -1 +1,635 @@
-export { u as useAnimatedText, a as useBowser, b as useDebounce, d as useEffectEvent, e as useInterval, f as useLiveRef, g as useMatchMedia, h as useOklch, i as useOutsideClick, k as usePreviousRender, j as usePreviousState, l as useRaf, m as useThrottle, n as useTimeout, c as useUniversalLayoutEffect, o as useWindowReady } from './useWindowReady-tUs-ONyG.js';
+import { n as useMergeRefs, t as mergeRefs } from "./useMergeRefs-BM2-gSLn.js";
+import React, { useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
+import gsap from "gsap";
+import { animate, useMotionValue } from "motion/react";
+import Bowser from "bowser";
+//#region src/hooks/usePrevious.ts
+var usePreviousState = (value) => {
+	const previousRef = useRef(void 0);
+	const currentRef = useRef(void 0);
+	useEffect(() => {
+		if (value !== currentRef.current) {
+			previousRef.current = currentRef.current;
+			currentRef.current = value;
+		}
+	}, [value]);
+	return previousRef.current;
+};
+var usePreviousRender = (value) => {
+	const previousRef = useRef(void 0);
+	useEffect(() => {
+		previousRef.current = value;
+	}, [value]);
+	return previousRef.current;
+};
+//#endregion
+//#region src/hooks/useAnimatedText/useAnimatedText.ts
+function useAnimatedText(text, delimiter) {
+	const resolvedDelimiter = delimiter === "word" ? " " : "";
+	const animatedCursor = useMotionValue(0);
+	const [cursor, setCursor] = useState(0);
+	const prevText = usePreviousRender(text);
+	const isSameText = text.startsWith(prevText ?? "");
+	const mountedRef = useRef(true);
+	useEffect(() => {
+		mountedRef.current = true;
+		return () => {
+			mountedRef.current = false;
+		};
+	}, []);
+	useEffect(() => {
+		if (!isSameText && mountedRef.current) {
+			animatedCursor.jump(0);
+			requestAnimationFrame(() => {
+				if (mountedRef.current) setCursor(0);
+			});
+		}
+	}, [isSameText, animatedCursor]);
+	useEffect(() => {
+		if (!mountedRef.current) return;
+		const controls = animate(animatedCursor, text.split(resolvedDelimiter).length, {
+			duration: 3,
+			ease: "easeOut",
+			onUpdate(latest) {
+				if (mountedRef.current) setCursor(Math.floor(latest));
+			}
+		});
+		return () => {
+			controls.stop();
+		};
+	}, [
+		animatedCursor,
+		isSameText,
+		text,
+		resolvedDelimiter
+	]);
+	return text.split(resolvedDelimiter).slice(0, cursor).join(resolvedDelimiter);
+}
+//#endregion
+//#region src/hooks/useControllableState.ts
+function useControllableState(controlledValue, defaultValue, onChange) {
+	const isControlled = controlledValue !== void 0;
+	const isControlledRef = useRef(isControlled);
+	const [internalValue, setInternalValue] = useState(defaultValue);
+	useEffect(() => {
+		if (process.env.NODE_ENV !== "production") {
+			if (isControlledRef.current !== isControlled) console.warn("Component switched between controlled and uncontrolled. Decide between using a controlled or uncontrolled value for the lifetime of the component.");
+		}
+		isControlledRef.current = isControlled;
+	});
+	return [isControlled ? controlledValue : internalValue, useCallback((next) => {
+		const resolve = (prev) => typeof next === "function" ? next(prev) : next;
+		if (!isControlledRef.current) setInternalValue((prev) => {
+			const nextValue = resolve(prev);
+			onChange?.(nextValue);
+			return nextValue;
+		});
+		else onChange?.(resolve(controlledValue));
+	}, [onChange, controlledValue])];
+}
+//#endregion
+//#region src/hooks/useBowser.ts
+var useBowser = () => {
+	const [browser] = useState(() => typeof window === "undefined" ? null : Bowser.parse(window.navigator.userAgent));
+	const [parser] = useState(() => typeof window === "undefined" ? null : Bowser.getParser(window.navigator.userAgent));
+	return useMemo(() => {
+		if (!parser || !browser) return null;
+		const browserName = parser.getBrowser().name;
+		const isDesktop = browser.platform.type === "desktop";
+		return {
+			isMobile: browser.platform.type === "mobile",
+			isDesktop,
+			isIOS: browser.os.name?.toLowerCase() === "ios",
+			isMacOS: browser.platform.type?.toLocaleLowerCase() === "desktop" && browser.platform.vendor?.toLowerCase() === "apple" && browser.os.name?.toLocaleLowerCase() === "macos",
+			isSafari: browserName ? Boolean(browserName.toLowerCase().match(/safari/)) : false,
+			isFirefox: browserName ? Boolean(browserName.toLowerCase().match(/firefox/)) : false,
+			isChrome: browserName ? Boolean(browserName.toLowerCase().match(/chrome/)) : false
+		};
+	}, [browser, parser]);
+};
+//#endregion
+//#region src/hooks/useLiveRef.ts
+var useLiveRef = (value) => {
+	const ref = useRef(value);
+	ref.current = value;
+	return ref;
+};
+//#endregion
+//#region src/hooks/useDebounce.ts
+/**
+* Custom hook that debounces a callback function to delay its execution until after
+* a specified wait time has elapsed since the last time it was invoked.
+*
+* Debouncing ensures that the callback is only executed once after a series of rapid calls,
+* waiting for a pause in the calls before executing.
+*
+* @param callback - The function to debounce
+* @param delay - The delay time (in milliseconds) to wait before executing the callback
+* @param options - Optional configuration object
+* @param options.maxWait - Maximum time before function must be invoked
+* @param options.leading - If true, invoke on the leading edge
+* @returns A debounced version of the callback function with a `cancel` method
+*
+* @example
+* ```tsx
+* const debouncedSearch = useDebounce((query: string) => {
+*   console.log('Searching for:', query)
+* }, 300)
+*
+* return <input onChange={(e) => debouncedSearch(e.target.value)} />
+* ```
+*
+* @example
+* ```tsx
+* // With maxWait and leading options
+* const debouncedSearch = useDebounce(
+*   (query: string) => console.log('Searching for:', query),
+*   300,
+*   { maxWait: 1000, leading: true }
+* )
+* ```
+*
+* @example
+* ```tsx
+* // Cancel pending debounced call
+* const debouncedSearch = useDebounce((query: string) => {
+*   console.log('Searching for:', query)
+* }, 300)
+*
+* debouncedSearch('test')
+* debouncedSearch.cancel() // Cancels the pending call
+* ```
+*/
+var useDebounce = (callback, delay, { maxWait, leading = false } = {}) => {
+	const timeoutRef = useRef(null);
+	const maxTimeoutMetadataRef = useRef(null);
+	const callbackRef = useLiveRef(callback);
+	const clearTimers = useCallback(() => {
+		if (timeoutRef.current) {
+			clearTimeout(timeoutRef.current);
+			timeoutRef.current = null;
+		}
+		if (maxTimeoutMetadataRef.current) {
+			clearTimeout(maxTimeoutMetadataRef.current.timeout);
+			maxTimeoutMetadataRef.current = null;
+		}
+	}, []);
+	const cancel = useCallback(() => {
+		clearTimers();
+	}, [clearTimers]);
+	const invokeCallback = useCallback((args) => {
+		clearTimers();
+		callbackRef.current(...args);
+	}, [clearTimers, callbackRef]);
+	useEffect(() => {
+		return clearTimers;
+	}, [clearTimers]);
+	const debounced = useCallback((...args) => {
+		const isNewCycle = timeoutRef.current === null;
+		if (leading && isNewCycle) callbackRef.current(...args);
+		if (timeoutRef.current) clearTimeout(timeoutRef.current);
+		if (maxWait && !maxTimeoutMetadataRef.current) maxTimeoutMetadataRef.current = {
+			timeout: setTimeout(() => {
+				if (maxTimeoutMetadataRef.current) invokeCallback(maxTimeoutMetadataRef.current.args);
+			}, maxWait),
+			args
+		};
+		else if (maxTimeoutMetadataRef.current) maxTimeoutMetadataRef.current.args = args;
+		timeoutRef.current = setTimeout(() => {
+			invokeCallback(args);
+		}, delay);
+	}, [
+		delay,
+		maxWait,
+		leading,
+		invokeCallback,
+		callbackRef
+	]);
+	return Object.assign(debounced, { cancel });
+};
+//#endregion
+//#region src/hooks/useEffectEvent.ts
+/**
+* Universal layout effect that uses useLayoutEffect in browser environments
+* and falls back to useEffect in SSR environments
+*/
+var useUniversalLayoutEffect = typeof window === "undefined" ? React.useEffect : React.useLayoutEffect;
+/**
+* Use `toString()` to prevent bundlers from trying to `import { useInsertionEffect } from 'react';`
+* @see https://github.com/radix-ui/primitives/blob/main/packages/react/id/src/id.tsx
+*/
+var useInsertionEffect = React["useInsertionEffect".toString()] || useUniversalLayoutEffect;
+function useEffectEvent(callback) {
+	const ref = React.useRef(() => {
+		throw new Error("Cannot call an event handler while rendering.");
+	});
+	useInsertionEffect(() => {
+		ref.current = callback;
+	}, [callback]);
+	return React.useCallback((...args) => {
+		return ref.current?.(...args);
+	}, []);
+}
+//#endregion
+//#region src/hooks/useInterval.ts
+var DEFAULT_DEPENDENCIES$1 = [];
+/**
+* Custom hook that manages an interval with automatic cleanup.
+* Provides a reliable way to handle intervals that are properly cleaned up
+* on component unmount or when dependencies change.
+*
+* @param callback - The function to execute on each interval
+* @param delay - The delay in milliseconds (null to clear the interval)
+* @param deps - Optional dependency array. If provided, interval restarts when deps change.
+*               If not provided, callback updates via ref without restarting interval.
+*
+* @example
+* ```tsx
+* // Runs continuously, callback updates via ref
+* useInterval(() => {
+*   console.log('This runs every second')
+* }, 1000)
+*
+* // Restarts interval when count changes
+* useInterval(() => {
+*   console.log('Count:', count)
+* }, 1000, [count])
+* ```
+*/
+var useInterval = (callback, delay = null, deps = DEFAULT_DEPENDENCIES$1) => {
+	const intervalRef = useRef(null);
+	const callbackRef = useRef(callback);
+	useEffect(() => {
+		callbackRef.current = callback;
+	}, [callback]);
+	useEffect(() => {
+		if (delay === null) return;
+		intervalRef.current = setInterval(() => {
+			callbackRef.current();
+		}, delay);
+		return () => {
+			if (intervalRef.current) {
+				clearInterval(intervalRef.current);
+				intervalRef.current = null;
+			}
+		};
+	}, [delay, ...deps]);
+};
+//#endregion
+//#region src/hooks/useMatchMedia.ts
+var hasMatchMedia = () => {
+	return typeof window?.matchMedia === "function";
+};
+var useMatchMedia = (query) => {
+	const [matches, setMatches] = useState(() => {
+		if (!hasMatchMedia()) return null;
+		try {
+			return window.matchMedia(query).matches;
+		} catch {
+			return null;
+		}
+	});
+	const matchMedia = useMemo(() => {
+		if (!hasMatchMedia()) return null;
+		try {
+			return window.matchMedia(query);
+		} catch {
+			return null;
+		}
+	}, [query]);
+	const handleChange = useCallback((event) => {
+		setMatches(event.matches);
+	}, []);
+	useEffect(() => {
+		if (!matchMedia) return;
+		requestAnimationFrame(() => {
+			setMatches(matchMedia.matches);
+		});
+		if (matchMedia.addEventListener) {
+			matchMedia.addEventListener("change", handleChange);
+			return () => matchMedia.removeEventListener("change", handleChange);
+		}
+		const legacyHandler = (event) => {
+			handleChange(event);
+		};
+		matchMedia.addListener(legacyHandler);
+		return () => matchMedia.removeListener(legacyHandler);
+	}, [matchMedia, handleChange]);
+	return matches;
+};
+//#endregion
+//#region src/hooks/useOklch.ts
+var globalCounterRef = { current: 0 };
+var useOklch = () => {
+	const hasSetP3Ref = useRef(false);
+	useEffect(() => {
+		if (typeof window === "undefined") return;
+		globalCounterRef.current += 1;
+		hasSetP3Ref.current = true;
+		document.body.dataset.p3 = "false";
+		return () => {
+			globalCounterRef.current -= 1;
+			if (globalCounterRef.current < 1 && hasSetP3Ref.current) {
+				document.body.dataset.p3 = void 0;
+				hasSetP3Ref.current = false;
+			}
+		};
+	}, []);
+};
+//#endregion
+//#region src/hooks/useOutsideClick.ts
+/**
+* Custom hook that detects clicks outside of a specified element and triggers a callback.
+*
+* Useful for implementing dropdown menus, modals, or any component that should close
+* when the user clicks outside of it.
+*
+* @param ref - React ref object pointing to the element to monitor
+* @param callback - Function to call when a click occurs outside the element
+* @param isActive - Whether the outside click detection should be active (default: true)
+*
+* @example
+* ```tsx
+* const ref = useRef<HTMLDivElement>(null)
+* const [isOpen, setIsOpen] = useState(false)
+*
+* useOutsideClick(ref, () => setIsOpen(false), isOpen)
+*
+* return <div ref={ref}>...</div>
+* ```
+*/
+var useOutsideClick = (ref, callback, isActive = true) => {
+	const liveCallbackRef = useLiveRef(callback);
+	useEffect(() => {
+		if (!isActive) return;
+		const handleClick = (event) => {
+			if (ref.current && !ref.current.contains(event.target)) liveCallbackRef.current();
+		};
+		document.addEventListener("pointerdown", handleClick, true);
+		return () => {
+			document.removeEventListener("pointerdown", handleClick, true);
+		};
+	}, [
+		ref,
+		isActive,
+		liveCallbackRef
+	]);
+};
+//#endregion
+//#region src/hooks/useRaf.ts
+/**
+* Custom hook that provides a requestAnimationFrame-based callback execution.
+* Useful for performance-critical animations and continuous updates that should
+* be synchronized with the browser's refresh rate.
+*
+* The callback will be executed on the next animation frame, and can be
+* controlled with an enabled flag for conditional execution.
+*
+* @param callback - The function to execute on each animation frame
+* @param enabled - Whether the animation loop should be active (default: true)
+* @returns A function to manually trigger the animation frame callback
+*
+* @example
+* ```tsx
+* const animate = useRaf(() => {
+*   // Animation logic here
+*   console.log('Animation frame')
+* }, isAnimating)
+*
+* // Manually trigger
+* animate()
+* ```
+*/
+var useRaf = (callback, enabled = true) => {
+	const rafIdRef = useRef(null);
+	const isRunningRef = useRef(false);
+	const enabledRef = useLiveRef(enabled);
+	const cleanup = useCallback(() => {
+		if (rafIdRef.current) {
+			cancelAnimationFrame(rafIdRef.current);
+			rafIdRef.current = null;
+		}
+		isRunningRef.current = false;
+	}, []);
+	const animate = useCallback(() => {
+		if (!enabledRef.current) return;
+		cleanup();
+		isRunningRef.current = true;
+		const loop = () => {
+			if (!enabledRef.current || !isRunningRef.current) {
+				isRunningRef.current = false;
+				return;
+			}
+			callback();
+			rafIdRef.current = requestAnimationFrame(loop);
+		};
+		rafIdRef.current = requestAnimationFrame(loop);
+	}, [
+		callback,
+		cleanup,
+		enabledRef
+	]);
+	useEffect(() => {
+		if (enabled) animate();
+		else cleanup();
+		return cleanup;
+	}, [
+		enabled,
+		animate,
+		cleanup
+	]);
+	return animate;
+};
+//#endregion
+//#region src/hooks/useThrottle.ts
+/**
+* Custom hook that throttles a callback function to limit how often it can be invoked.
+*
+* Throttling ensures that the callback is executed at most once per specified time interval,
+* regardless of how many times the throttled function is called.
+*
+* @param callback - The function to throttle
+* @param delay - The minimum time interval (in milliseconds) between executions
+* @returns A throttled version of the callback function
+*
+* @example
+* ```tsx
+* const throttledClick = useThrottle(() => {
+*   console.log('Button clicked')
+* }, 500)
+*
+* return <button onClick={throttledClick}>Click me</button>
+* ```
+*/
+var useThrottle = (callback, delay) => {
+	const lastExecuted = useRef(0);
+	const timeoutRef = useRef(null);
+	useEffect(() => {
+		return () => {
+			if (timeoutRef.current) {
+				clearTimeout(timeoutRef.current);
+				timeoutRef.current = null;
+			}
+		};
+	}, [callback, delay]);
+	return useCallback((...args) => {
+		const now = Date.now();
+		if (now - lastExecuted.current >= delay) {
+			callback(...args);
+			lastExecuted.current = now;
+		} else {
+			if (timeoutRef.current) clearTimeout(timeoutRef.current);
+			timeoutRef.current = setTimeout(() => {
+				callback(...args);
+				lastExecuted.current = Date.now();
+				timeoutRef.current = null;
+			}, delay - (now - lastExecuted.current));
+		}
+	}, [callback, delay]);
+};
+//#endregion
+//#region src/hooks/useTimeout.ts
+var DEFAULT_DEPENDENCIES = [];
+/**
+* Custom hook that manages a timeout with automatic cleanup.
+* Provides a reliable way to handle timeouts that are properly cleaned up
+* on component unmount or when dependencies change.
+*
+* @param callback - The function to execute after the delay
+* @param delay - The delay in milliseconds (null to clear the timeout)
+* @param deps - Optional dependency array. If provided, timeout restarts when deps change.
+*               If not provided, callback updates via ref without restarting timeout.
+*
+* @example
+* ```tsx
+* // Runs once, callback updates via ref
+* useTimeout(() => {
+*   console.log('This runs after 1 second')
+* }, 1000)
+*
+* // Restarts timeout when count changes
+* useTimeout(() => {
+*   console.log('Count:', count)
+* }, 1000, [count])
+* ```
+*/
+var useTimeout = (callback, delay = null, deps = DEFAULT_DEPENDENCIES) => {
+	const timeoutRef = useRef(null);
+	const callbackRef = useRef(callback);
+	useEffect(() => {
+		callbackRef.current = callback;
+	}, [callback]);
+	useEffect(() => {
+		if (delay === null) return;
+		timeoutRef.current = setTimeout(() => {
+			callbackRef.current();
+		}, delay);
+		return () => {
+			if (timeoutRef.current) {
+				clearTimeout(timeoutRef.current);
+				timeoutRef.current = null;
+			}
+		};
+	}, [delay, ...deps]);
+};
+//#endregion
+//#region src/hooks/useWindowReady.tsx
+var useWindowReady = () => {
+	const [ready, setReady] = useState(false);
+	useEffect(() => {
+		const timer = setTimeout(() => setReady(true), 0);
+		return () => clearTimeout(timer);
+	}, []);
+	return ready;
+};
+//#endregion
+//#region src/hooks/useReducedMotion.ts
+var QUERY = "(prefers-reduced-motion: reduce)";
+function useReducedMotion() {
+	const [reduced, setReduced] = useState(() => {
+		if (typeof window === "undefined") return false;
+		return window.matchMedia(QUERY).matches;
+	});
+	useEffect(() => {
+		const mql = window.matchMedia(QUERY);
+		const handler = (e) => setReduced(e.matches);
+		mql.addEventListener("change", handler);
+		return () => mql.removeEventListener("change", handler);
+	}, []);
+	return reduced;
+}
+//#endregion
+//#region src/hooks/useGsapContext.ts
+/**
+* Creates a GSAP context scoped to the given ref.
+* All animations created inside the callback are automatically
+* reverted on unmount — preventing DOM leak bugs.
+*/
+function useGsapContext(scope, callback, deps = []) {
+	const ctxRef = useRef(null);
+	useEffect(() => {
+		if (!scope.current) return;
+		const ctx = gsap.context((context) => {
+			const typedContext = context;
+			ctxRef.current = typedContext;
+			const cleanup = callback(typedContext);
+			if (typeof cleanup === "function") typedContext.add(cleanup);
+		}, scope.current);
+		ctxRef.current = ctx;
+		return () => {
+			ctx.revert();
+			ctxRef.current = null;
+		};
+	}, [scope, ...deps]);
+	return ctxRef;
+}
+//#endregion
+//#region src/hooks/useFormField.ts
+function useFormField(options = {}) {
+	const { id: externalId, hasError = false, hasHint = false } = options;
+	const autoId = useId();
+	const fieldId = externalId ?? autoId;
+	const ids = useMemo(() => ({
+		fieldId,
+		labelId: `${fieldId}-label`,
+		errorId: `${fieldId}-error`,
+		hintId: `${fieldId}-hint`,
+		descriptionId: `${fieldId}-description`
+	}), [fieldId]);
+	const describedBy = useMemo(() => {
+		const parts = [];
+		if (hasError) parts.push(ids.errorId);
+		if (hasHint && !hasError) parts.push(ids.hintId);
+		return parts.length > 0 ? parts.join(" ") : void 0;
+	}, [
+		hasError,
+		hasHint,
+		ids.errorId,
+		ids.hintId
+	]);
+	return useMemo(() => ({
+		ids,
+		labelProps: {
+			htmlFor: fieldId,
+			id: ids.labelId
+		},
+		fieldProps: {
+			id: fieldId,
+			"aria-describedby": describedBy,
+			"aria-invalid": hasError || void 0,
+			"aria-errormessage": hasError ? ids.errorId : void 0
+		},
+		errorProps: {
+			id: ids.errorId,
+			role: "alert"
+		},
+		hintProps: { id: ids.hintId }
+	}), [
+		ids,
+		fieldId,
+		describedBy,
+		hasError
+	]);
+}
+//#endregion
+export { mergeRefs, useAnimatedText, useBowser, useControllableState, useDebounce, useEffectEvent, useFormField, useGsapContext, useInterval, useLiveRef, useMatchMedia, useMergeRefs, useOklch, useOutsideClick, usePreviousRender, usePreviousState, useRaf, useReducedMotion, useThrottle, useTimeout, useUniversalLayoutEffect, useWindowReady };