@pyreon/hooks 0.0.2

package/lib/index.js

@@ -0,0 +1,617 @@
+import { onMount, onUnmount } from "@pyreon/core";
+import { computed, effect, signal, watch } from "@pyreon/reactivity";
+import { useTheme } from "@pyreon/styler";
+import { get, throttle } from "@pyreon/ui-core";
+
+//#region src/useBreakpoint.ts
+const defaultBreakpoints = {
+	xs: 0,
+	sm: 576,
+	md: 768,
+	lg: 992,
+	xl: 1200
+};
+/**
+* Return the currently active breakpoint name as a reactive signal.
+*/
+function useBreakpoint(breakpoints = defaultBreakpoints) {
+	const sorted = Object.entries(breakpoints).sort(([, a], [, b]) => a - b);
+	const active = signal(getActive(sorted));
+	let rafId;
+	function getActive(bps) {
+		if (typeof window === "undefined") return bps[0]?.[0] ?? "";
+		const w = window.innerWidth;
+		let result = bps[0]?.[0] ?? "";
+		for (const [name, min] of bps) if (w >= min) result = name;
+		else break;
+		return result;
+	}
+	function onResize() {
+		if (rafId !== void 0) cancelAnimationFrame(rafId);
+		rafId = requestAnimationFrame(() => {
+			const next = getActive(sorted);
+			if (next !== active.peek()) active.set(next);
+		});
+	}
+	onMount(() => {
+		window.addEventListener("resize", onResize);
+	});
+	onUnmount(() => {
+		window.removeEventListener("resize", onResize);
+		if (rafId !== void 0) cancelAnimationFrame(rafId);
+	});
+	return active;
+}
+
+//#endregion
+//#region src/useClickOutside.ts
+/**
+* Call handler when a click occurs outside the target element.
+*/
+function useClickOutside(getEl, handler) {
+	const listener = (e) => {
+		const el = getEl();
+		if (!el || el.contains(e.target)) return;
+		handler();
+	};
+	onMount(() => {
+		document.addEventListener("mousedown", listener, true);
+		document.addEventListener("touchstart", listener, true);
+	});
+	onUnmount(() => {
+		document.removeEventListener("mousedown", listener, true);
+		document.removeEventListener("touchstart", listener, true);
+	});
+}
+
+//#endregion
+//#region src/useMediaQuery.ts
+/**
+* Subscribe to a CSS media query, returns a reactive boolean.
+*/
+function useMediaQuery(query) {
+	const matches = signal(false);
+	let mql;
+	const onChange = (e) => {
+		matches.set(e.matches);
+	};
+	onMount(() => {
+		mql = window.matchMedia(query);
+		matches.set(mql.matches);
+		mql.addEventListener("change", onChange);
+	});
+	onUnmount(() => {
+		mql?.removeEventListener("change", onChange);
+	});
+	return matches;
+}
+
+//#endregion
+//#region src/useColorScheme.ts
+/**
+* Returns the OS color scheme preference as 'light' or 'dark'.
+*/
+function useColorScheme() {
+	const prefersDark = useMediaQuery("(prefers-color-scheme: dark)");
+	return computed(() => prefersDark() ? "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.
+*
+* Returns [getter, setter] where getter is a reactive function.
+*/
+const useControllableState = ({ value, defaultValue, onChange }) => {
+	const internal = signal(defaultValue);
+	const onChangeFn = onChange;
+	const isControlled = value !== void 0;
+	const getter = () => isControlled ? value : internal();
+	const setValue = (next) => {
+		const current = isControlled ? value : internal();
+		const nextValue = typeof next === "function" ? next(current) : next;
+		if (!isControlled) internal.set(nextValue);
+		onChangeFn?.(nextValue);
+	};
+	return [getter, setValue];
+};
+
+//#endregion
+//#region src/useDebouncedCallback.ts
+/**
+* Returns a 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 currentCallback = callback;
+	let timer = null;
+	let lastArgs = null;
+	const cancel = () => {
+		if (timer != null) {
+			clearTimeout(timer);
+			timer = null;
+		}
+		lastArgs = null;
+	};
+	const flush = () => {
+		if (timer != null && lastArgs != null) {
+			clearTimeout(timer);
+			timer = null;
+			currentCallback(...lastArgs);
+			lastArgs = null;
+		}
+	};
+	const debounced = (...args) => {
+		lastArgs = args;
+		if (timer != null) clearTimeout(timer);
+		timer = setTimeout(() => {
+			timer = null;
+			currentCallback(...args);
+			lastArgs = null;
+		}, delay);
+	};
+	onUnmount(() => cancel());
+	return Object.assign(debounced, {
+		cancel,
+		flush
+	});
+};
+
+//#endregion
+//#region src/useDebouncedValue.ts
+/**
+* Return a debounced version of a reactive value.
+*/
+function useDebouncedValue(getter, delayMs) {
+	const debounced = signal(getter());
+	let timer;
+	effect(() => {
+		const val = getter();
+		if (timer !== void 0) clearTimeout(timer);
+		timer = setTimeout(() => {
+			debounced.set(val);
+		}, delayMs);
+	});
+	onUnmount(() => {
+		if (timer !== void 0) clearTimeout(timer);
+	});
+	return debounced;
+}
+
+//#endregion
+//#region src/useElementSize.ts
+/**
+* Observe element dimensions reactively via ResizeObserver.
+*/
+function useElementSize(getEl) {
+	const size = signal({
+		width: 0,
+		height: 0
+	});
+	let observer;
+	onMount(() => {
+		const el = getEl();
+		if (!el) return void 0;
+		observer = new ResizeObserver(([entry]) => {
+			if (!entry) return;
+			const { width, height } = entry.contentRect;
+			size.set({
+				width,
+				height
+			});
+		});
+		observer.observe(el);
+		const rect = el.getBoundingClientRect();
+		size.set({
+			width: rect.width,
+			height: rect.height
+		});
+	});
+	onUnmount(() => {
+		observer?.disconnect();
+	});
+	return size;
+}
+
+//#endregion
+//#region src/useFocus.ts
+/**
+* Track focus state reactively.
+*/
+function useFocus() {
+	const focused = signal(false);
+	return {
+		focused,
+		props: {
+			onFocus: () => focused.set(true),
+			onBlur: () => focused.set(false)
+		}
+	};
+}
+
+//#endregion
+//#region src/useFocusTrap.ts
+const FOCUSABLE = "a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex=\"-1\"])";
+/**
+* Trap Tab/Shift+Tab focus within a container element.
+*/
+function useFocusTrap(getEl) {
+	const listener = (e) => {
+		if (e.key !== "Tab") return;
+		const el = getEl();
+		if (!el) return;
+		const focusable = Array.from(el.querySelectorAll(FOCUSABLE));
+		if (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();
+		}
+	};
+	onMount(() => {
+		document.addEventListener("keydown", listener);
+	});
+	onUnmount(() => {
+		document.removeEventListener("keydown", listener);
+	});
+}
+
+//#endregion
+//#region src/useHover.ts
+/**
+* Track hover state reactively.
+*
+* @example
+* const { hovered, props } = useHover()
+* h('div', { ...props, class: () => hovered() ? 'active' : '' })
+*/
+function useHover() {
+	const hovered = signal(false);
+	return {
+		hovered,
+		props: {
+			onMouseEnter: () => hovered.set(true),
+			onMouseLeave: () => hovered.set(false)
+		}
+	};
+}
+
+//#endregion
+//#region src/useIntersection.ts
+/**
+* Observe element intersection reactively.
+*/
+function useIntersection(getEl, options) {
+	const entry = signal(null);
+	let observer;
+	onMount(() => {
+		const el = getEl();
+		if (!el) return void 0;
+		observer = new IntersectionObserver(([e]) => {
+			if (e) entry.set(e);
+		}, options);
+		observer.observe(el);
+	});
+	onUnmount(() => {
+		observer?.disconnect();
+	});
+	return 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 currentCallback = callback;
+	let intervalId = null;
+	const start = () => {
+		if (delay === null) return;
+		intervalId = setInterval(() => currentCallback(), delay);
+	};
+	const stop = () => {
+		if (intervalId != null) {
+			clearInterval(intervalId);
+			intervalId = null;
+		}
+	};
+	start();
+	onUnmount(() => stop());
+};
+
+//#endregion
+//#region src/useIsomorphicLayoutEffect.ts
+const useIsomorphicLayoutEffect = typeof window !== "undefined" ? onMount : onMount;
+
+//#endregion
+//#region src/useKeyboard.ts
+/**
+* Listen for a specific key press.
+*/
+function useKeyboard(key, handler, options) {
+	const eventName = options?.event ?? "keydown";
+	const listener = (e) => {
+		const ke = e;
+		if (ke.key === key) handler(ke);
+	};
+	onMount(() => {
+		(options?.target ?? document).addEventListener(eventName, listener);
+	});
+	onUnmount(() => {
+		(options?.target ?? document).removeEventListener(eventName, listener);
+	});
+}
+
+//#endregion
+//#region src/useLatest.ts
+/**
+* Returns a ref-like object that always holds the latest value.
+* Useful to avoid stale closures in callbacks and effects.
+*
+* In Pyreon, since the component body runs once, this simply wraps
+* the value in a mutable object. The caller is expected to call this
+* once and update `.current` manually if needed, or pass a reactive
+* getter to read the latest value.
+*/
+const useLatest = (value) => {
+	return { current: value };
+};
+
+//#endregion
+//#region src/useMergedRef.ts
+/**
+* Merges multiple refs (callback or object) into a single callback ref.
+* Handles undefined, callback refs, and object refs with `.current`.
+*/
+const useMergedRef = (...refs) => {
+	return (node) => {
+		for (const ref of refs) {
+			if (!ref) continue;
+			if (typeof ref === "function") ref(node);
+			else ref.current = node;
+		}
+	};
+};
+
+//#endregion
+//#region src/usePrevious.ts
+/**
+* Track the previous value of a reactive getter.
+* Returns undefined on first access.
+*/
+function usePrevious(getter) {
+	const prev = signal(void 0);
+	let current;
+	effect(() => {
+		const next = getter();
+		prev.set(current);
+		current = next;
+	});
+	return prev;
+}
+
+//#endregion
+//#region src/useReducedMotion.ts
+/**
+* Returns true when the user prefers reduced motion.
+*/
+function useReducedMotion() {
+	return 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 rootSize is set in the theme.
+*/
+const useRootSize = () => {
+	const rootSize = useTheme()?.rootSize ?? 16;
+	return {
+		rootSize,
+		pxToRem: (px) => `${px / rootSize}rem`,
+		remToPx: (rem) => rem * rootSize
+	};
+};
+
+//#endregion
+//#region src/useScrollLock.ts
+let lockCount = 0;
+let savedOverflow = "";
+/**
+* Lock page scroll. Uses reference counting for concurrent locks.
+* Returns an unlock function.
+*/
+function useScrollLock() {
+	let isLocked = false;
+	const lock = () => {
+		if (isLocked) return;
+		isLocked = true;
+		if (lockCount === 0) {
+			savedOverflow = document.body.style.overflow;
+			document.body.style.overflow = "hidden";
+		}
+		lockCount++;
+	};
+	const unlock = () => {
+		if (!isLocked) return;
+		isLocked = false;
+		lockCount--;
+		if (lockCount === 0) document.body.style.overflow = savedOverflow;
+	};
+	onUnmount(() => {
+		if (isLocked) unlock();
+	});
+	return {
+		lock,
+		unlock
+	};
+}
+
+//#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 (multiplier) => `${unit * multiplier}px`;
+};
+
+//#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 = useTheme();
+	if (!theme) return void 0;
+	return get(theme, path);
+};
+
+//#endregion
+//#region src/useThrottledCallback.ts
+/**
+* Returns a throttled version of the callback.
+* Uses `throttle` from `@pyreon/ui-core`.
+* Always calls the latest callback (no stale closures).
+* Cleans up on unmount.
+*/
+const useThrottledCallback = (callback, delay) => {
+	const currentCallback = callback;
+	const throttled = throttle((...args) => currentCallback(...args), delay);
+	onUnmount(() => throttled.cancel());
+	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 currentCallback = callback;
+	let timer = null;
+	const clear = () => {
+		if (timer != null) {
+			clearTimeout(timer);
+			timer = null;
+		}
+	};
+	const reset = () => {
+		clear();
+		if (delay !== null) timer = setTimeout(() => {
+			timer = null;
+			currentCallback();
+		}, delay);
+	};
+	reset();
+	onUnmount(() => clear());
+	return {
+		reset,
+		clear
+	};
+};
+
+//#endregion
+//#region src/useToggle.ts
+/**
+* Simple boolean toggle.
+*/
+function useToggle(initial = false) {
+	const value = signal(initial);
+	return {
+		value,
+		toggle: () => value.update((v) => !v),
+		setTrue: () => value.set(true),
+		setFalse: () => value.set(false)
+	};
+}
+
+//#endregion
+//#region src/useUpdateEffect.ts
+/**
+* Like `effect` but skips the initial value — only fires on updates.
+*
+* In Pyreon, this is implemented using `watch()` which already skips
+* the initial value by default (immediate defaults to false).
+*
+* @param source - A reactive getter to watch
+* @param callback - Called when source changes, receives (newVal, oldVal)
+*/
+const useUpdateEffect = (source, callback) => {
+	const stop = watch(source, callback);
+	onUnmount(() => stop());
+};
+
+//#endregion
+//#region src/useWindowResize.ts
+/**
+* Track window dimensions reactively with throttling.
+*/
+function useWindowResize(throttleMs = 200) {
+	const size = signal({
+		width: typeof window !== "undefined" ? window.innerWidth : 0,
+		height: typeof window !== "undefined" ? window.innerHeight : 0
+	});
+	let timer;
+	function onResize() {
+		if (timer !== void 0) return;
+		timer = setTimeout(() => {
+			timer = void 0;
+			size.set({
+				width: window.innerWidth,
+				height: window.innerHeight
+			});
+		}, throttleMs);
+	}
+	onMount(() => {
+		window.addEventListener("resize", onResize);
+	});
+	onUnmount(() => {
+		window.removeEventListener("resize", onResize);
+		if (timer !== void 0) clearTimeout(timer);
+	});
+	return size;
+}
+
+//#endregion
+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