@vitus-labs/hooks 2.0.0-alpha.9 → 2.0.0-beta.1

package/lib/index.js

@@ -1,6 +1,292 @@
-import { useCallback, useEffect, useRef, useState } from "react";
-import { throttle } from "@vitus-labs/core";
+import { context, get, throttle } from "@vitus-labs/core";
+import { useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 
+//#region src/useBreakpoint.ts
+/**
+* Returns the name of the currently active breakpoint from the
+* unistyle/core theme context (e.g. `"xs"`, `"md"`, `"lg"`).
+*
+* Reads `theme.breakpoints` from the nearest `Provider` and
+* subscribes to viewport changes via `matchMedia`.
+*
+* Returns `undefined` when no Provider or breakpoints are available.
+*/
+const useBreakpoint = () => {
+	const breakpoints = useContext(context)?.theme?.breakpoints;
+	const sorted = useMemo(() => {
+		if (!breakpoints) return [];
+		return Object.entries(breakpoints).sort(([, a], [, b]) => a - b);
+	}, [breakpoints]);
+	const [current, setCurrent] = useState(() => {
+		if (sorted.length === 0) return void 0;
+		if (typeof window === "undefined") return sorted[0]?.[0];
+		const width = window.innerWidth;
+		let match = sorted[0]?.[0];
+		for (const [name, min] of sorted) if (width >= min) match = name;
+		return match;
+	});
+	useEffect(() => {
+		if (sorted.length === 0) return void 0;
+		let raf = 0;
+		const update = () => {
+			raf = 0;
+			const width = window.innerWidth;
+			let match = sorted[0]?.[0];
+			for (const [name, min] of sorted) if (width >= min) match = name;
+			setCurrent(match);
+		};
+		const onResize = () => {
+			if (raf === 0) raf = requestAnimationFrame(update);
+		};
+		window.addEventListener("resize", onResize, { passive: true });
+		return () => {
+			if (raf !== 0) cancelAnimationFrame(raf);
+			window.removeEventListener("resize", onResize);
+		};
+	}, [sorted]);
+	return current;
+};
+
+//#endregion
+//#region src/useClickOutside.ts
+/**
+* Calls `handler` when a click (mousedown or touchstart) occurs
+* outside the element referenced by `ref`.
+*/
+const useClickOutside = (ref, handler) => {
+	const handlerRef = useRef(handler);
+	handlerRef.current = handler;
+	useEffect(() => {
+		const listener = (event) => {
+			const el = ref.current;
+			const target = event.target;
+			if (!el || !target || el.contains(target)) return;
+			handlerRef.current(event);
+		};
+		document.addEventListener("mousedown", listener);
+		document.addEventListener("touchstart", listener);
+		return () => {
+			document.removeEventListener("mousedown", listener);
+			document.removeEventListener("touchstart", listener);
+		};
+	}, [ref]);
+};
+
+//#endregion
+//#region src/useMediaQuery.ts
+/**
+* Subscribes to a CSS media query and returns whether it currently matches.
+* Uses `window.matchMedia` with an event listener for live updates.
+*/
+const useMediaQuery = (query) => {
+	const [matches, setMatches] = useState(useCallback(() => typeof window !== "undefined" ? window.matchMedia(query).matches : false, [query]));
+	useEffect(() => {
+		const mql = window.matchMedia(query);
+		setMatches(mql.matches);
+		const handler = (e) => setMatches(e.matches);
+		mql.addEventListener("change", handler);
+		return () => mql.removeEventListener("change", handler);
+	}, [query]);
+	return matches;
+};
+
+//#endregion
+//#region src/useColorScheme.ts
+/**
+* Returns the user's preferred color scheme (`"light"` or `"dark"`).
+* Reacts to OS-level preference changes in real time.
+* Pairs with rocketstyle's `mode` system.
+*/
+const useColorScheme = () => {
+	return useMediaQuery("(prefers-color-scheme: dark)") ? "dark" : "light";
+};
+
+//#endregion
+//#region src/useControllableState.ts
+/**
+* Unified controlled/uncontrolled state pattern.
+* When `value` is provided the component is controlled; otherwise
+* internal state is used with `defaultValue` as the initial value.
+* The `onChange` callback fires in both modes.
+*/
+const useControllableState = ({ value, defaultValue, onChange }) => {
+	const [internal, setInternal] = useState(defaultValue);
+	const onChangeRef = useRef(onChange);
+	onChangeRef.current = onChange;
+	const isControlled = value !== void 0;
+	const current = isControlled ? value : internal;
+	return [current, useCallback((next) => {
+		const nextValue = typeof next === "function" ? next(current) : next;
+		if (!isControlled) setInternal(nextValue);
+		onChangeRef.current?.(nextValue);
+	}, [current, isControlled])];
+};
+
+//#endregion
+//#region src/useDebouncedCallback.ts
+/**
+* Returns a stable debounced version of the callback.
+* The returned function has `.cancel()` and `.flush()` methods.
+* Always calls the latest callback (no stale closures).
+* Cleans up on unmount.
+*/
+const useDebouncedCallback = (callback, delay) => {
+	const callbackRef = useRef(callback);
+	callbackRef.current = callback;
+	const timerRef = useRef(null);
+	const lastArgsRef = useRef(null);
+	const cancel = useCallback(() => {
+		if (timerRef.current != null) {
+			clearTimeout(timerRef.current);
+			timerRef.current = null;
+		}
+		lastArgsRef.current = null;
+	}, []);
+	const flush = useCallback(() => {
+		if (timerRef.current != null && lastArgsRef.current != null) {
+			clearTimeout(timerRef.current);
+			timerRef.current = null;
+			callbackRef.current(...lastArgsRef.current);
+			lastArgsRef.current = null;
+		}
+	}, []);
+	useEffect(() => cancel, [cancel]);
+	const debounced = useCallback((...args) => {
+		lastArgsRef.current = args;
+		if (timerRef.current != null) clearTimeout(timerRef.current);
+		timerRef.current = setTimeout(() => {
+			timerRef.current = null;
+			callbackRef.current(...args);
+			lastArgsRef.current = null;
+		}, delay);
+	}, [delay]);
+	return Object.assign(debounced, {
+		cancel,
+		flush
+	});
+};
+
+//#endregion
+//#region src/useDebouncedValue.ts
+/**
+* Returns a debounced version of the value that only updates
+* after `delay` ms of inactivity.
+*
+* @example
+* ```ts
+* const [search, setSearch] = useState('')
+* const debouncedSearch = useDebouncedValue(search, 300)
+* ```
+*/
+const useDebouncedValue = (value, delay) => {
+	const [debounced, setDebounced] = useState(value);
+	useEffect(() => {
+		const id = setTimeout(() => setDebounced(value), delay);
+		return () => clearTimeout(id);
+	}, [value, delay]);
+	return debounced;
+};
+
+//#endregion
+//#region src/useElementSize.ts
+/**
+* Tracks an element's `width` and `height` via `ResizeObserver`.
+* Returns `[ref, { width, height }]` — pass `ref` as a callback ref.
+*/
+const useElementSize = () => {
+	const [size, setSize] = useState({
+		width: 0,
+		height: 0
+	});
+	const observerRef = useRef(null);
+	return [useCallback((node) => {
+		if (observerRef.current) {
+			observerRef.current.disconnect();
+			observerRef.current = null;
+		}
+		if (!node || typeof ResizeObserver === "undefined") return;
+		const observer = new ResizeObserver((entries) => {
+			const entry = entries[0];
+			if (!entry) return;
+			const { width, height } = entry.contentRect;
+			setSize((prev) => prev.width === width && prev.height === height ? prev : {
+				width,
+				height
+			});
+		});
+		observer.observe(node);
+		observerRef.current = observer;
+		const rect = node.getBoundingClientRect();
+		setSize((prev) => prev.width === rect.width && prev.height === rect.height ? prev : {
+			width: rect.width,
+			height: rect.height
+		});
+	}, []), size];
+};
+
+//#endregion
+//#region src/useFocus.ts
+/**
+* Simple focus-state hook that returns a boolean plus stable
+* `onFocus`/`onBlur` handlers ready to spread onto an element.
+*/
+const useFocus = (initial = false) => {
+	const [focused, setFocused] = useState(initial);
+	return {
+		focused,
+		onFocus: useCallback(() => setFocused(true), []),
+		onBlur: useCallback(() => setFocused(false), [])
+	};
+};
+
+//#endregion
+//#region src/useFocusTrap.ts
+const FOCUSABLE = "a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex=\"-1\"])";
+const wrapFocus = (e, target) => {
+	if (!target) return;
+	e.preventDefault();
+	target.focus();
+};
+/**
+* Traps keyboard focus within the referenced container.
+* Tab and Shift+Tab cycle through focusable elements inside.
+* Useful for modals, dialogs, and dropdown menus.
+*
+* Focusable elements are cached and only re-queried when DOM mutations
+* inside the container add/remove nodes — not on every Tab keypress.
+*/
+const useFocusTrap = (ref, enabled = true) => {
+	useEffect(() => {
+		if (!enabled) return void 0;
+		const container = ref.current;
+		if (!container) return void 0;
+		let focusable = null;
+		const refresh = () => {
+			focusable = container.querySelectorAll(FOCUSABLE);
+		};
+		refresh();
+		const observer = new MutationObserver(refresh);
+		observer.observe(container, {
+			childList: true,
+			subtree: true
+		});
+		const handler = (e) => {
+			if (e.key !== "Tab" || !focusable || focusable.length === 0) return;
+			const first = focusable[0];
+			const last = focusable[focusable.length - 1];
+			const active = document.activeElement;
+			if (e.shiftKey && active === first) wrapFocus(e, last);
+			else if (!e.shiftKey && active === last) wrapFocus(e, first);
+		};
+		document.addEventListener("keydown", handler);
+		return () => {
+			observer.disconnect();
+			document.removeEventListener("keydown", handler);
+		};
+	}, [ref, enabled]);
+};
+
+//#endregion
 //#region src/useHover.ts
 /**
 * Simple hover-state hook that returns a boolean plus stable
@@ -15,6 +301,299 @@ const useHover = (initial = false) => {
 	};
 };
 
+//#endregion
+//#region src/useIntersection.ts
+/**
+* Observes an element's intersection with the viewport (or a root element).
+* Returns `[ref, entry]` — pass `ref` as a callback ref.
+*/
+const useIntersection = (options = {}) => {
+	const { threshold = 0, rootMargin = "0px", root = null } = options;
+	const [entry, setEntry] = useState(null);
+	const observerRef = useRef(null);
+	return [useCallback((node) => {
+		if (observerRef.current) {
+			observerRef.current.disconnect();
+			observerRef.current = null;
+		}
+		if (!node || typeof IntersectionObserver === "undefined") return;
+		const observer = new IntersectionObserver((entries) => {
+			setEntry(entries[0] ?? null);
+		}, {
+			threshold,
+			rootMargin,
+			root
+		});
+		observer.observe(node);
+		observerRef.current = observer;
+	}, [
+		threshold,
+		rootMargin,
+		root
+	]), entry];
+};
+
+//#endregion
+//#region src/useInterval.ts
+/**
+* Declarative `setInterval` with auto-cleanup.
+* Pass `null` as `delay` to pause the interval.
+* Always calls the latest callback (no stale closures).
+*/
+const useInterval = (callback, delay) => {
+	const callbackRef = useRef(callback);
+	callbackRef.current = callback;
+	useEffect(() => {
+		if (delay === null) return void 0;
+		const id = setInterval(() => callbackRef.current(), delay);
+		return () => clearInterval(id);
+	}, [delay]);
+};
+
+//#endregion
+//#region src/useIsomorphicLayoutEffect.ts
+/**
+* `useLayoutEffect` on the client, `useEffect` on the server.
+* Avoids the React SSR warning about useLayoutEffect.
+*/
+const useIsomorphicLayoutEffect = typeof window !== "undefined" ? useLayoutEffect : useEffect;
+
+//#endregion
+//#region src/useKeyboard.ts
+/**
+* Listens for a specific keyboard key and calls the handler.
+* Matches `event.key` (e.g. `"Escape"`, `"Enter"`, `"a"`).
+* Always calls the latest handler (no stale closures).
+*
+* @example
+* ```ts
+* useKeyboard('Escape', () => setOpen(false))
+* ```
+*/
+const useKeyboard = (key, handler) => {
+	const handlerRef = useRef(handler);
+	handlerRef.current = handler;
+	useEffect(() => {
+		const listener = (e) => {
+			if (e.key === key) handlerRef.current(e);
+		};
+		window.addEventListener("keydown", listener);
+		return () => window.removeEventListener("keydown", listener);
+	}, [key]);
+};
+
+//#endregion
+//#region src/useLatest.ts
+/**
+* Returns a ref that always holds the latest value.
+* Useful to avoid stale closures in callbacks and effects.
+*/
+const useLatest = (value) => {
+	const ref = useRef(value);
+	ref.current = value;
+	return ref;
+};
+
+//#endregion
+//#region src/useMergedRef.ts
+/**
+* Merges multiple refs (callback or object) into a single stable callback ref.
+* Handles null, callback refs, and object refs with `.current`.
+*/
+const useMergedRef = (...refs) => {
+	return useCallback((node) => {
+		for (const ref of refs) {
+			if (!ref) continue;
+			if (typeof ref === "function") ref(node);
+			else ref.current = node;
+		}
+	}, refs);
+};
+
+//#endregion
+//#region src/usePrevious.ts
+/**
+* Returns the value from the previous render.
+* Returns `undefined` on the first render.
+*/
+const usePrevious = (value) => {
+	const ref = useRef(void 0);
+	useEffect(() => {
+		ref.current = value;
+	});
+	return ref.current;
+};
+
+//#endregion
+//#region src/useReducedMotion.ts
+/**
+* Returns `true` when the user prefers reduced motion.
+* Use to disable or simplify animations for accessibility.
+*/
+const useReducedMotion = () => useMediaQuery("(prefers-reduced-motion: reduce)");
+
+//#endregion
+//#region src/useRootSize.ts
+/**
+* Returns `rootSize` from the theme context along with
+* `pxToRem` and `remToPx` conversion utilities.
+*
+* Defaults to `16` when no Provider is mounted.
+*/
+const useRootSize = () => {
+	const rootSize = useContext(context)?.theme?.rootSize ?? 16;
+	return useMemo(() => ({
+		rootSize,
+		pxToRem: (px) => `${px / rootSize}rem`,
+		remToPx: (rem) => rem * rootSize
+	}), [rootSize]);
+};
+
+//#endregion
+//#region src/useScrollLock.ts
+let lockCount = 0;
+let originalOverflow;
+/**
+* Locks page scroll by setting `overflow: hidden` on `document.body`.
+* Uses a reference counter so concurrent locks don't clobber each other.
+*/
+const useScrollLock = (enabled) => {
+	useEffect(() => {
+		if (!enabled) return void 0;
+		if (lockCount === 0) originalOverflow = document.body.style.overflow;
+		lockCount++;
+		document.body.style.overflow = "hidden";
+		return () => {
+			lockCount--;
+			if (lockCount === 0) {
+				document.body.style.overflow = originalOverflow ?? "";
+				originalOverflow = void 0;
+			}
+		};
+	}, [enabled]);
+};
+
+//#endregion
+//#region src/useSpacing.ts
+/**
+* Returns a `spacing(n)` function that computes spacing values
+* based on `rootSize` from the theme.
+*
+* @param base - Base spacing unit in px (defaults to `rootSize / 2`, i.e. 8px)
+*
+* @example
+* ```ts
+* const spacing = useSpacing()
+* spacing(1)  // "8px"
+* spacing(2)  // "16px"
+* spacing(0.5) // "4px"
+* ```
+*/
+const useSpacing = (base) => {
+	const { rootSize } = useRootSize();
+	const unit = base ?? rootSize / 2;
+	return useMemo(() => (multiplier) => `${unit * multiplier}px`, [unit]);
+};
+
+//#endregion
+//#region src/useThemeValue.ts
+/**
+* Deep-reads a value from the current theme by dot-separated path.
+*
+* @example
+* ```ts
+* const primary = useThemeValue<string>('colors.primary')
+* const columns = useThemeValue<number>('grid.columns')
+* ```
+*/
+const useThemeValue = (path) => {
+	const theme = useContext(context)?.theme;
+	if (!theme) return void 0;
+	return get(theme, path);
+};
+
+//#endregion
+//#region src/useThrottledCallback.ts
+/**
+* Returns a stable throttled version of the callback.
+* Uses `throttle` from `@vitus-labs/core`.
+* Always calls the latest callback (no stale closures).
+* Cleans up on unmount.
+*/
+const useThrottledCallback = (callback, delay) => {
+	const callbackRef = useRef(callback);
+	callbackRef.current = callback;
+	const throttled = useMemo(() => throttle((...args) => callbackRef.current(...args), delay), [delay]);
+	useEffect(() => () => throttled.cancel(), [throttled]);
+	return throttled;
+};
+
+//#endregion
+//#region src/useTimeout.ts
+/**
+* Declarative `setTimeout` with auto-cleanup.
+* Pass `null` as `delay` to disable. Returns `reset` and `clear` controls.
+* Always calls the latest callback (no stale closures).
+*/
+const useTimeout = (callback, delay) => {
+	const callbackRef = useRef(callback);
+	callbackRef.current = callback;
+	const timerRef = useRef(null);
+	const clear = useCallback(() => {
+		if (timerRef.current != null) {
+			clearTimeout(timerRef.current);
+			timerRef.current = null;
+		}
+	}, []);
+	const reset = useCallback(() => {
+		clear();
+		if (delay !== null) timerRef.current = setTimeout(() => {
+			timerRef.current = null;
+			callbackRef.current();
+		}, delay);
+	}, [delay, clear]);
+	useEffect(() => {
+		reset();
+		return clear;
+	}, [reset, clear]);
+	return {
+		reset,
+		clear
+	};
+};
+
+//#endregion
+//#region src/useToggle.ts
+/**
+* Boolean state with `toggle`, `setTrue`, and `setFalse` helpers.
+* Returns `[value, toggle, setTrue, setFalse]`.
+*/
+const useToggle = (initial = false) => {
+	const [value, setValue] = useState(initial);
+	return [
+		value,
+		useCallback(() => setValue((v) => !v), []),
+		useCallback(() => setValue(true), []),
+		useCallback(() => setValue(false), [])
+	];
+};
+
+//#endregion
+//#region src/useUpdateEffect.ts
+/**
+* Like `useEffect` but skips the initial mount — only fires on updates.
+*/
+const useUpdateEffect = (effect, deps) => {
+	const mounted = useRef(false);
+	useEffect(() => {
+		if (!mounted.current) {
+			mounted.current = true;
+			return;
+		}
+		return effect();
+	}, deps);
+};
+
 //#endregion
 //#region src/useWindowResize.ts
 /**
@@ -53,5 +632,5 @@ const useWindowResize = ({ throttleDelay = 200, onChange } = {}, { width = 0, he
 };
 
 //#endregion
-export { useHover, useWindowResize };
+export { useBreakpoint, useClickOutside, useColorScheme, useControllableState, useDebouncedCallback, useDebouncedValue, useElementSize, useFocus, useFocusTrap, useHover, useIntersection, useInterval, useIsomorphicLayoutEffect, useKeyboard, useLatest, useMediaQuery, useMergedRef, usePrevious, useReducedMotion, useRootSize, useScrollLock, useSpacing, useThemeValue, useThrottledCallback, useTimeout, useToggle, useUpdateEffect, useWindowResize };
 //# sourceMappingURL=index.js.map