@vitus-labs/hooks 2.0.0-alpha.27 → 2.0.0-alpha.29

package/lib/index.d.ts

@@ -108,6 +108,9 @@ type UseFocusTrap = (ref: {
  * 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.
  */
 declare const useFocusTrap: UseFocusTrap;
 //#endregion
@@ -228,7 +231,7 @@ declare const useRootSize: UseRootSize;
 type UseScrollLock = (enabled: boolean) => void;
 /**
  * Locks page scroll by setting `overflow: hidden` on `document.body`.
- * Restores the original overflow value on disable or unmount.
+ * Uses a reference counter so concurrent locks don't clobber each other.
  */
 declare const useScrollLock: UseScrollLock;
 //#endregion

package/lib/index.js

@@ -27,24 +27,21 @@ const useBreakpoint = () => {
 	});
 	useEffect(() => {
 		if (sorted.length === 0) return void 0;
-		const mqls = [];
+		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);
 		};
-		for (const [, min] of sorted) {
-			const mql = window.matchMedia(`(min-width: ${min}px)`);
-			const handler = () => update();
-			mql.addEventListener("change", handler);
-			mqls.push({
-				mql,
-				handler
-			});
-		}
+		const onResize = () => {
+			if (raf === 0) raf = requestAnimationFrame(update);
+		};
+		window.addEventListener("resize", onResize, { passive: true });
 		return () => {
-			for (const { mql, handler } of mqls) mql.removeEventListener("change", handler);
+			if (raf !== 0) cancelAnimationFrame(raf);
+			window.removeEventListener("resize", onResize);
 		};
 	}, [sorted]);
 	return current;
@@ -62,7 +59,8 @@ const useClickOutside = (ref, handler) => {
 	useEffect(() => {
 		const listener = (event) => {
 			const el = ref.current;
-			if (!el || el.contains(event.target)) return;
+			const target = event.target;
+			if (!el || !target || el.contains(target)) return;
 			handlerRef.current(event);
 		};
 		document.addEventListener("mousedown", listener);
@@ -206,7 +204,7 @@ const useElementSize = () => {
 			observerRef.current.disconnect();
 			observerRef.current = null;
 		}
-		if (!node) return;
+		if (!node || typeof ResizeObserver === "undefined") return;
 		const observer = new ResizeObserver((entries) => {
 			const entry = entries[0];
 			if (!entry) return;
@@ -219,7 +217,7 @@ const useElementSize = () => {
 		observer.observe(node);
 		observerRef.current = observer;
 		const rect = node.getBoundingClientRect();
-		setSize({
+		setSize((prev) => prev.width === rect.width && prev.height === rect.height ? prev : {
 			width: rect.width,
 			height: rect.height
 		});
@@ -244,32 +242,47 @@ const useFocus = (initial = 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" || !ref.current) return;
-			const focusable = ref.current.querySelectorAll(FOCUSABLE);
-			if (focusable.length === 0) return;
+			if (e.key !== "Tab" || !focusable || focusable.length === 0) return;
 			const first = focusable[0];
 			const last = focusable[focusable.length - 1];
-			if (e.shiftKey) {
-				if (document.activeElement === first) {
-					e.preventDefault();
-					last?.focus();
-				}
-			} else if (document.activeElement === last) {
-				e.preventDefault();
-				first?.focus();
-			}
+			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 () => document.removeEventListener("keydown", handler);
+		return () => {
+			observer.disconnect();
+			document.removeEventListener("keydown", handler);
+		};
 	}, [ref, enabled]);
 };
 
@@ -303,7 +316,7 @@ const useIntersection = (options = {}) => {
 			observerRef.current.disconnect();
 			observerRef.current = null;
 		}
-		if (!node) return;
+		if (!node || typeof IntersectionObserver === "undefined") return;
 		const observer = new IntersectionObserver((entries) => {
 			setEntry(entries[0] ?? null);
 		}, {
@@ -438,17 +451,24 @@ const useRootSize = () => {
 
 //#endregion
 //#region src/useScrollLock.ts
+let lockCount = 0;
+let originalOverflow;
 /**
 * Locks page scroll by setting `overflow: hidden` on `document.body`.
-* Restores the original overflow value on disable or unmount.
+* Uses a reference counter so concurrent locks don't clobber each other.
 */
 const useScrollLock = (enabled) => {
 	useEffect(() => {
 		if (!enabled) return void 0;
-		const original = document.body.style.overflow;
+		if (lockCount === 0) originalOverflow = document.body.style.overflow;
+		lockCount++;
 		document.body.style.overflow = "hidden";
 		return () => {
-			document.body.style.overflow = original;
+			lockCount--;
+			if (lockCount === 0) {
+				document.body.style.overflow = originalOverflow ?? "";
+				originalOverflow = void 0;
+			}
 		};
 	}, [enabled]);
 };

package/lib/vitus-labs-hooks.native.js

@@ -0,0 +1,435 @@
+import { context, get, throttle } from "@vitus-labs/core";
+import { useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { AccessibilityInfo, Appearance, Dimensions } from "react-native";
+
+//#region src/useBreakpoint.native.ts
+/**
+* Returns the name of the currently active breakpoint from the
+* unistyle/core theme context (e.g. `"xs"`, `"md"`, `"lg"`).
+*
+* Uses React Native's `Dimensions` API instead of `matchMedia`.
+*/
+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 getMatch = useCallback((width) => {
+		let match = sorted[0]?.[0];
+		for (const [name, min] of sorted) if (width >= min) match = name;
+		return match;
+	}, [sorted]);
+	const [current, setCurrent] = useState(() => {
+		if (sorted.length === 0) return void 0;
+		return getMatch(Dimensions.get("window").width);
+	});
+	useEffect(() => {
+		if (sorted.length === 0) return void 0;
+		const sub = Dimensions.addEventListener("change", ({ window }) => {
+			setCurrent(getMatch(window.width));
+		});
+		return () => sub.remove();
+	}, [sorted, getMatch]);
+	return current;
+};
+
+//#endregion
+//#region src/useColorScheme.native.ts
+const toScheme = (value) => value === "dark" ? "dark" : "light";
+/**
+* Returns the user's preferred color scheme (`"light"` or `"dark"`).
+* Uses React Native's `Appearance` API and subscribes to changes.
+*/
+const useColorScheme = () => {
+	const [scheme, setScheme] = useState(() => toScheme(Appearance.getColorScheme()));
+	useEffect(() => {
+		const sub = Appearance.addChangeListener(({ colorScheme }) => {
+			setScheme(toScheme(colorScheme));
+		});
+		return () => sub.remove();
+	}, []);
+	return scheme;
+};
+
+//#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/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/useHover.ts
+/**
+* Simple hover-state hook that returns a boolean plus stable
+* `onMouseEnter`/`onMouseLeave` handlers ready to spread onto an element.
+*/
+const useHover = (initial = false) => {
+	const [hover, handleHover] = useState(initial);
+	return {
+		hover,
+		onMouseEnter: useCallback(() => handleHover(true), []),
+		onMouseLeave: useCallback(() => handleHover(false), [])
+	};
+};
+
+//#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.native.ts
+/**
+* No-op on React Native. Physical keyboard events are not reliably
+* available across all RN platforms. Use `TextInput.onKeyPress` or
+* a hardware keyboard library for specific use cases.
+*/
+const useKeyboard = () => {};
+
+//#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.native.ts
+/**
+* Returns `true` when the user prefers reduced motion.
+* Uses React Native's `AccessibilityInfo.isReduceMotionEnabled()`.
+*/
+const useReducedMotion = () => {
+	const [reduced, setReduced] = useState(false);
+	useEffect(() => {
+		AccessibilityInfo.isReduceMotionEnabled().then(setReduced);
+		const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduced);
+		return () => sub.remove();
+	}, []);
+	return reduced;
+};
+
+//#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/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.native.ts
+/**
+* Tracks the React Native window dimensions.
+* Uses `Dimensions` API instead of `window.innerWidth/innerHeight`.
+* The `throttleDelay` parameter is accepted for API compat but not used
+* (RN dimension events fire infrequently).
+*/
+const useWindowResize = ({ onChange } = {}, { width, height } = {}) => {
+	const [windowSize, setWindowSize] = useState(() => {
+		const dim = Dimensions.get("window");
+		return {
+			width: width ?? dim.width,
+			height: height ?? dim.height
+		};
+	});
+	const onChangeRef = useRef(onChange);
+	onChangeRef.current = onChange;
+	useEffect(() => {
+		const sub = Dimensions.addEventListener("change", ({ window }) => {
+			const sizes = {
+				width: window.width,
+				height: window.height
+			};
+			setWindowSize(sizes);
+			onChangeRef.current?.(sizes);
+		});
+		return () => sub.remove();
+	}, []);
+	return windowSize;
+};
+
+//#endregion
+export { useBreakpoint, useColorScheme, useControllableState, useDebouncedCallback, useDebouncedValue, useFocus, useHover, useInterval, useIsomorphicLayoutEffect, useKeyboard, useLatest, useMergedRef, usePrevious, useReducedMotion, useRootSize, useSpacing, useThemeValue, useThrottledCallback, useTimeout, useToggle, useUpdateEffect, useWindowResize };
+//# sourceMappingURL=vitus-labs-hooks.native.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vitus-labs/hooks",
-  "version": "2.0.0-alpha.27",
+  "version": "2.0.0-alpha.29",
   "license": "MIT",
   "author": "Vit Bokisch <vit@bokisch.cz>",
   "maintainers": [
@@ -10,10 +10,13 @@
   "sideEffects": false,
   "exports": {
     "source": "./src/index.ts",
+    "react-native": "./lib/vitus-labs-hooks.native.js",
     "import": "./lib/index.js",
     "types": "./lib/index.d.ts"
   },
   "types": "./lib/index.d.ts",
+  "react-native": "./lib/vitus-labs-hooks.native.js",
+  "main": "./lib/index.js",
   "files": [
     "lib",
     "!lib/**/*.map",
@@ -49,14 +52,20 @@
     "node": ">= 18"
   },
   "peerDependencies": {
-    "@vitus-labs/core": "2.0.0-alpha.26",
-    "react": ">= 19"
+    "@vitus-labs/core": "2.0.0-alpha.29",
+    "react": ">= 19",
+    "react-native": ">= 0.76"
   },
-  "devDependencies": {
-    "@vitus-labs/core": "2.0.0-alpha.27",
-    "@vitus-labs/tools-rolldown": "1.9.1-alpha.19",
-    "@vitus-labs/tools-storybook": "1.9.1-alpha.19",
-    "@vitus-labs/tools-typescript": "1.9.1-alpha.19"
+  "peerDependenciesMeta": {
+    "react-native": {
+      "optional": true
+    }
   },
-  "gitHead": "6230c7b4eb1f8fe52bd47275cf72cdcab706cb45"
+  "devDependencies": {
+    "@vitus-labs/core": "workspace:*",
+    "@vitus-labs/tools-rolldown": "2.0.0",
+    "@vitus-labs/tools-storybook": "2.0.0",
+    "@vitus-labs/tools-typescript": "2.0.0",
+    "react-native": ">=0.84.1"
+  }
 }

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2023-present Vit Bokisch
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.