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

package/README.md

@@ -1,6 +1,6 @@
 # @vitus-labs/hooks
 
-Lightweight React hooks for common UI interactions.
+28 React hooks for UI interactions, state management, DOM observation, accessibility, and theming. 2.15KB gzipped.
 
 [![npm](https://img.shields.io/npm/v/@vitus-labs/hooks)](https://www.npmjs.com/package/@vitus-labs/hooks)
 [![license](https://img.shields.io/npm/l/@vitus-labs/hooks)](https://github.com/vitus-labs/ui-system/blob/main/LICENSE)
@@ -13,63 +13,288 @@ npm install @vitus-labs/hooks
 
 ## Hooks
 
-### useHover
+### Primitives
 
-Tracks hover state with stable callback references.
+#### useLatest
 
-```tsx
-import { useHover } from '@vitus-labs/hooks'
+Returns a ref that always holds the latest value. Avoids stale closures in callbacks and effects.
+
+```ts
+const ref = useLatest(callback)
+// ref.current is always the latest callback
+```
 
-const MyComponent = () => {
-  const { hover, onMouseEnter, onMouseLeave } = useHover()
+#### useToggle
 
-  return (
-    <div
-      onMouseEnter={onMouseEnter}
-      onMouseLeave={onMouseLeave}
-      style={{ background: hover ? '#f0f0f0' : '#fff' }}
-    >
-      {hover ? 'Hovered' : 'Hover me'}
-    </div>
-  )
-}
+Boolean state with `toggle`, `setTrue`, and `setFalse` helpers.
+
+```ts
+const [isOpen, toggle, open, close] = useToggle(false)
 ```
 
-**Parameters:**
+#### usePrevious
 
-| Param | Type | Default | Description |
-| ----- | ---- | ------- | ----------- |
-| initialValue | `boolean` | `false` | Initial hover state |
+Returns the value from the previous render.
 
-**Returns:** `{ hover: boolean, onMouseEnter: () => void, onMouseLeave: () => void }`
+```ts
+const prev = usePrevious(count)
+// undefined on first render, then the previous value
+```
 
-### useWindowResize
+### Callbacks
 
-Tracks viewport dimensions with throttled updates.
+#### useDebouncedCallback
+
+Stable debounced function with `.cancel()` and `.flush()`.
+
+```ts
+const search = useDebouncedCallback((query: string) => {
+  fetchResults(query)
+}, 300)
+
+search('hello') // fires after 300ms of inactivity
+search.cancel()  // cancel pending
+search.flush()   // fire immediately
+```
+
+#### useThrottledCallback
+
+Stable throttled function with `.cancel()`. Uses `throttle` from `@vitus-labs/core`.
+
+```ts
+const handleScroll = useThrottledCallback(() => {
+  updatePosition()
+}, 100)
+```
+
+### State
+
+#### useDebouncedValue
+
+Returns a debounced version of the value that only updates after `delay` ms of inactivity.
+
+```ts
+const [search, setSearch] = useState('')
+const debouncedSearch = useDebouncedValue(search, 300)
+```
+
+#### useControllableState
+
+Unified controlled/uncontrolled state pattern.
+
+```ts
+const [value, setValue] = useControllableState({
+  value: props.value,       // controlled (optional)
+  defaultValue: '',         // uncontrolled fallback
+  onChange: props.onChange,  // fires in both modes
+})
+```
+
+### Effects
+
+#### useUpdateEffect
+
+Like `useEffect` but skips the initial mount.
+
+```ts
+useUpdateEffect(() => {
+  // only fires on updates, not on mount
+  saveToStorage(value)
+}, [value])
+```
+
+#### useIsomorphicLayoutEffect
+
+`useLayoutEffect` on the client, `useEffect` on the server. Avoids SSR warnings.
+
+```ts
+useIsomorphicLayoutEffect(() => {
+  measureElement()
+}, [])
+```
+
+#### useInterval
+
+Declarative `setInterval` with auto-cleanup. Pass `null` to pause.
+
+```ts
+useInterval(() => tick(), 1000)     // every second
+useInterval(() => tick(), null)      // paused
+```
+
+#### useTimeout
+
+Declarative `setTimeout` with `reset` and `clear` controls.
+
+```ts
+const { reset, clear } = useTimeout(() => {
+  showNotification()
+}, 5000)
+```
+
+### DOM & Observers
+
+#### useElementSize
+
+Tracks element `width` and `height` via `ResizeObserver`.
+
+```tsx
+const [ref, { width, height }] = useElementSize()
+return <div ref={ref}>Size: {width}x{height}</div>
+```
+
+#### useIntersection
+
+`IntersectionObserver` wrapper for visibility detection.
 
 ```tsx
-import { useWindowResize } from '@vitus-labs/hooks'
+const [ref, entry] = useIntersection({ threshold: 0.5 })
+const isVisible = entry?.isIntersecting
+return <div ref={ref}>{isVisible ? 'Visible' : 'Hidden'}</div>
+```
+
+### Interaction
+
+#### useHover
+
+Tracks hover state with stable callback references.
+
+```ts
+const { hover, onMouseEnter, onMouseLeave } = useHover()
+```
 
-const Layout = () => {
-  const { width, height } = useWindowResize({
-    throttleDelay: 300,
-    onChange: ({ width }) => console.log('Width:', width),
-  })
+#### useFocus
 
-  return <div>Viewport: {width} x {height}</div>
-}
+Tracks focus state with stable callback references.
+
+```ts
+const { focused, onFocus, onBlur } = useFocus()
+```
+
+#### useClickOutside
+
+Calls handler when a click occurs outside the referenced element.
+
+```ts
+const ref = useRef<HTMLDivElement>(null)
+useClickOutside(ref, () => setOpen(false))
+```
+
+#### useScrollLock
+
+Locks page scroll by setting `overflow: hidden` on `document.body`.
+
+```ts
+useScrollLock(isModalOpen)
+```
+
+#### useKeyboard
+
+Listens for a specific keyboard key.
+
+```ts
+useKeyboard('Escape', () => setOpen(false))
+```
+
+#### useFocusTrap
+
+Traps Tab/Shift+Tab focus within a container. Essential for modals and dialogs.
+
+```ts
+const ref = useRef<HTMLDivElement>(null)
+useFocusTrap(ref, isOpen)
+```
+
+### Responsive
+
+#### useMediaQuery
+
+Subscribes to a CSS media query and returns whether it matches.
+
+```ts
+const isDesktop = useMediaQuery('(min-width: 1024px)')
+```
+
+#### useBreakpoint
+
+Returns the currently active breakpoint name from the theme context.
+
+```ts
+const bp = useBreakpoint() // "xs" | "sm" | "md" | "lg" | "xl" | undefined
+```
+
+#### useColorScheme
+
+Returns the user's preferred color scheme. Pairs with rocketstyle's `mode`.
+
+```ts
+const scheme = useColorScheme() // "light" | "dark"
+```
+
+#### useReducedMotion
+
+Returns `true` when the user prefers reduced motion.
+
+```ts
+const reduced = useReducedMotion()
+const duration = reduced ? 0 : 300
+```
+
+### Theme & Styling
+
+#### useThemeValue
+
+Deep-reads a value from the current theme by dot-separated path.
+
+```ts
+const primary = useThemeValue<string>('colors.primary')
+const columns = useThemeValue<number>('grid.columns')
+```
+
+#### useRootSize
+
+Returns `rootSize` from the theme with px/rem conversion utilities.
+
+```ts
+const { rootSize, pxToRem, remToPx } = useRootSize()
+pxToRem(32) // "2rem"
+remToPx(2)  // 32
+```
+
+#### useSpacing
+
+Returns a spacing function based on the theme's root size.
+
+```ts
+const spacing = useSpacing()
+spacing(1)   // "8px"
+spacing(2)   // "16px"
+spacing(0.5) // "4px"
+```
+
+### Composition
+
+#### useMergedRef
+
+Merges multiple refs (callback or object) into a single stable callback ref.
+
+```tsx
+const Component = forwardRef((props, ref) => {
+  const localRef = useRef(null)
+  const merged = useMergedRef(ref, localRef)
+  return <div ref={merged} />
+})
 ```
 
-**Parameters:**
+### Viewport
 
-| Param | Type | Default | Description |
-| ----- | ---- | ------- | ----------- |
-| params.throttleDelay | `number` | `200` | Milliseconds between resize handler calls |
-| params.onChange | `(sizes) => void` | — | Callback fired on each resize |
-| initialValues.width | `number` | `0` | Initial width (useful for SSR) |
-| initialValues.height | `number` | `0` | Initial height (useful for SSR) |
+#### useWindowResize
 
-**Returns:** `{ width: number, height: number }`
+Tracks viewport dimensions with throttled updates.
+
+```ts
+const { width, height } = useWindowResize({ throttleDelay: 300 })
+```
 
 ## Peer Dependencies
 

package/lib/index.d.ts

@@ -1,3 +1,116 @@
+import { DependencyList, EffectCallback, Ref, useLayoutEffect } from "react";
+
+//#region src/useBreakpoint.d.ts
+type UseBreakpoint = () => string | undefined;
+/**
+ * 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.
+ */
+declare const useBreakpoint: UseBreakpoint;
+//#endregion
+//#region src/useClickOutside.d.ts
+type UseClickOutside = (ref: {
+  current: Element | null;
+}, handler: (event: Event) => void) => void;
+/**
+ * Calls `handler` when a click (mousedown or touchstart) occurs
+ * outside the element referenced by `ref`.
+ */
+declare const useClickOutside: UseClickOutside;
+//#endregion
+//#region src/useColorScheme.d.ts
+type UseColorScheme = () => 'light' | 'dark';
+/**
+ * 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.
+ */
+declare const useColorScheme: UseColorScheme;
+//#endregion
+//#region src/useControllableState.d.ts
+type UseControllableStateOptions<T> = {
+  value?: T;
+  defaultValue: T;
+  onChange?: (value: T) => void;
+};
+type UseControllableState = <T>(options: UseControllableStateOptions<T>) => [T, (next: T | ((prev: T) => T)) => void];
+/**
+ * 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.
+ */
+declare const useControllableState: UseControllableState;
+//#endregion
+//#region src/useDebouncedCallback.d.ts
+type DebouncedFn<T extends (...args: any[]) => any> = {
+  (...args: Parameters<T>): void;
+  cancel: () => void;
+  flush: () => void;
+};
+type UseDebouncedCallback = <T extends (...args: any[]) => any>(callback: T, delay: number) => DebouncedFn<T>;
+/**
+ * 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.
+ */
+declare const useDebouncedCallback: UseDebouncedCallback;
+//#endregion
+//#region src/useDebouncedValue.d.ts
+type UseDebouncedValue = <T>(value: T, delay: number) => T;
+/**
+ * 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)
+ * ```
+ */
+declare const useDebouncedValue: UseDebouncedValue;
+//#endregion
+//#region src/useElementSize.d.ts
+type Size = {
+  width: number;
+  height: number;
+};
+type UseElementSize = () => [(node: Element | null) => void, Size];
+/**
+ * Tracks an element's `width` and `height` via `ResizeObserver`.
+ * Returns `[ref, { width, height }]` — pass `ref` as a callback ref.
+ */
+declare const useElementSize: UseElementSize;
+//#endregion
+//#region src/useFocus.d.ts
+type UseFocus = (initialValue?: boolean) => {
+  focused: boolean;
+  onFocus: () => void;
+  onBlur: () => void;
+};
+/**
+ * Simple focus-state hook that returns a boolean plus stable
+ * `onFocus`/`onBlur` handlers ready to spread onto an element.
+ */
+declare const useFocus: UseFocus;
+//#endregion
+//#region src/useFocusTrap.d.ts
+type UseFocusTrap = (ref: {
+  current: HTMLElement | null;
+}, enabled?: boolean) => void;
+/**
+ * Traps keyboard focus within the referenced container.
+ * Tab and Shift+Tab cycle through focusable elements inside.
+ * Useful for modals, dialogs, and dropdown menus.
+ */
+declare const useFocusTrap: UseFocusTrap;
+//#endregion
 //#region src/useHover.d.ts
 type UseHover = (initialValue?: boolean) => {
   hover: boolean;
@@ -10,6 +123,187 @@ type UseHover = (initialValue?: boolean) => {
  */
 declare const useHover: UseHover;
 //#endregion
+//#region src/useIntersection.d.ts
+type UseIntersectionOptions = {
+  threshold?: number | number[];
+  rootMargin?: string;
+  root?: Element | null;
+};
+type UseIntersection = (options?: UseIntersectionOptions) => [(node: Element | null) => void, IntersectionObserverEntry | null];
+/**
+ * Observes an element's intersection with the viewport (or a root element).
+ * Returns `[ref, entry]` — pass `ref` as a callback ref.
+ */
+declare const useIntersection: UseIntersection;
+//#endregion
+//#region src/useInterval.d.ts
+type UseInterval = (callback: () => void, delay: number | null) => void;
+/**
+ * Declarative `setInterval` with auto-cleanup.
+ * Pass `null` as `delay` to pause the interval.
+ * Always calls the latest callback (no stale closures).
+ */
+declare const useInterval: UseInterval;
+//#endregion
+//#region src/useIsomorphicLayoutEffect.d.ts
+/**
+ * `useLayoutEffect` on the client, `useEffect` on the server.
+ * Avoids the React SSR warning about useLayoutEffect.
+ */
+declare const useIsomorphicLayoutEffect: typeof useLayoutEffect;
+type UseIsomorphicLayoutEffect = typeof useIsomorphicLayoutEffect;
+//#endregion
+//#region src/useKeyboard.d.ts
+type UseKeyboard = (key: string, handler: (event: KeyboardEvent) => void) => void;
+/**
+ * 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))
+ * ```
+ */
+declare const useKeyboard: UseKeyboard;
+//#endregion
+//#region src/useLatest.d.ts
+type UseLatest = <T>(value: T) => {
+  readonly current: T;
+};
+/**
+ * Returns a ref that always holds the latest value.
+ * Useful to avoid stale closures in callbacks and effects.
+ */
+declare const useLatest: UseLatest;
+//#endregion
+//#region src/useMediaQuery.d.ts
+type UseMediaQuery = (query: string) => boolean;
+/**
+ * Subscribes to a CSS media query and returns whether it currently matches.
+ * Uses `window.matchMedia` with an event listener for live updates.
+ */
+declare const useMediaQuery: UseMediaQuery;
+//#endregion
+//#region src/useMergedRef.d.ts
+type UseMergedRef = <T>(...refs: (Ref<T> | undefined)[]) => (node: T | null) => void;
+/**
+ * Merges multiple refs (callback or object) into a single stable callback ref.
+ * Handles null, callback refs, and object refs with `.current`.
+ */
+declare const useMergedRef: <T>(...refs: (Ref<T> | undefined)[]) => (node: T | null) => void;
+//#endregion
+//#region src/usePrevious.d.ts
+type UsePrevious = <T>(value: T) => T | undefined;
+/**
+ * Returns the value from the previous render.
+ * Returns `undefined` on the first render.
+ */
+declare const usePrevious: UsePrevious;
+//#endregion
+//#region src/useReducedMotion.d.ts
+type UseReducedMotion = () => boolean;
+/**
+ * Returns `true` when the user prefers reduced motion.
+ * Use to disable or simplify animations for accessibility.
+ */
+declare const useReducedMotion: UseReducedMotion;
+//#endregion
+//#region src/useRootSize.d.ts
+type RootSizeResult = {
+  rootSize: number;
+  pxToRem: (px: number) => string;
+  remToPx: (rem: number) => number;
+};
+type UseRootSize = () => RootSizeResult;
+/**
+ * Returns `rootSize` from the theme context along with
+ * `pxToRem` and `remToPx` conversion utilities.
+ *
+ * Defaults to `16` when no Provider is mounted.
+ */
+declare const useRootSize: UseRootSize;
+//#endregion
+//#region src/useScrollLock.d.ts
+type UseScrollLock = (enabled: boolean) => void;
+/**
+ * Locks page scroll by setting `overflow: hidden` on `document.body`.
+ * Restores the original overflow value on disable or unmount.
+ */
+declare const useScrollLock: UseScrollLock;
+//#endregion
+//#region src/useSpacing.d.ts
+type UseSpacing = (base?: number) => (multiplier: number) => string;
+/**
+ * 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"
+ * ```
+ */
+declare const useSpacing: UseSpacing;
+//#endregion
+//#region src/useThemeValue.d.ts
+type UseThemeValue = <T = unknown>(path: string) => T | undefined;
+/**
+ * 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')
+ * ```
+ */
+declare const useThemeValue: UseThemeValue;
+//#endregion
+//#region src/useThrottledCallback.d.ts
+type ThrottledFn<T extends (...args: any[]) => any> = {
+  (...args: Parameters<T>): void;
+  cancel: () => void;
+};
+type UseThrottledCallback = <T extends (...args: any[]) => any>(callback: T, delay: number) => ThrottledFn<T>;
+/**
+ * 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.
+ */
+declare const useThrottledCallback: UseThrottledCallback;
+//#endregion
+//#region src/useTimeout.d.ts
+type UseTimeout = (callback: () => void, delay: number | null) => {
+  reset: () => void;
+  clear: () => void;
+};
+/**
+ * Declarative `setTimeout` with auto-cleanup.
+ * Pass `null` as `delay` to disable. Returns `reset` and `clear` controls.
+ * Always calls the latest callback (no stale closures).
+ */
+declare const useTimeout: UseTimeout;
+//#endregion
+//#region src/useToggle.d.ts
+type UseToggle = (initialValue?: boolean) => [boolean, () => void, () => void, () => void];
+/**
+ * Boolean state with `toggle`, `setTrue`, and `setFalse` helpers.
+ * Returns `[value, toggle, setTrue, setFalse]`.
+ */
+declare const useToggle: UseToggle;
+//#endregion
+//#region src/useUpdateEffect.d.ts
+type UseUpdateEffect = (effect: EffectCallback, deps?: DependencyList) => void;
+/**
+ * Like `useEffect` but skips the initial mount — only fires on updates.
+ */
+declare const useUpdateEffect: UseUpdateEffect;
+//#endregion
 //#region src/useWindowResize.d.ts
 type Sizes = {
   width: number;
@@ -27,5 +321,5 @@ type UseWindowResize = (params?: Partial<{
  */
 declare const useWindowResize: UseWindowResize;
 //#endregion
-export { type UseHover, type UseWindowResize, useHover, useWindowResize };
+export { type UseBreakpoint, type UseClickOutside, type UseColorScheme, type UseControllableState, type UseDebouncedCallback, type UseDebouncedValue, type UseElementSize, type UseFocus, type UseFocusTrap, type UseHover, type UseIntersection, type UseInterval, type UseIsomorphicLayoutEffect, type UseKeyboard, type UseLatest, type UseMediaQuery, type UseMergedRef, type UsePrevious, type UseReducedMotion, type UseRootSize, type UseScrollLock, type UseSpacing, type UseThemeValue, type UseThrottledCallback, type UseTimeout, type UseToggle, type UseUpdateEffect, type UseWindowResize, 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=index2.d.ts.map

package/lib/index.js

@@ -1,6 +1,279 @@
-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;
+		const mqls = [];
+		const update = () => {
+			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
+			});
+		}
+		return () => {
+			for (const { mql, handler } of mqls) mql.removeEventListener("change", handler);
+		};
+	}, [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;
+			if (!el || el.contains(event.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) 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({
+			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\"])";
+/**
+* Traps keyboard focus within the referenced container.
+* Tab and Shift+Tab cycle through focusable elements inside.
+* Useful for modals, dialogs, and dropdown menus.
+*/
+const useFocusTrap = (ref, enabled = true) => {
+	useEffect(() => {
+		if (!enabled) return void 0;
+		const handler = (e) => {
+			if (e.key !== "Tab" || !ref.current) return;
+			const focusable = ref.current.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();
+			}
+		};
+		document.addEventListener("keydown", handler);
+		return () => document.removeEventListener("keydown", handler);
+	}, [ref, enabled]);
+};
+
+//#endregion
 //#region src/useHover.ts
 /**
 * Simple hover-state hook that returns a boolean plus stable
@@ -15,6 +288,292 @@ 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) 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
+/**
+* Locks page scroll by setting `overflow: hidden` on `document.body`.
+* Restores the original overflow value on disable or unmount.
+*/
+const useScrollLock = (enabled) => {
+	useEffect(() => {
+		if (!enabled) return void 0;
+		const original = document.body.style.overflow;
+		document.body.style.overflow = "hidden";
+		return () => {
+			document.body.style.overflow = original;
+		};
+	}, [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 +612,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vitus-labs/hooks",
-  "version": "2.0.0-alpha.25",
+  "version": "2.0.0-alpha.27",
   "license": "MIT",
   "author": "Vit Bokisch <vit@bokisch.cz>",
   "maintainers": [
@@ -49,14 +49,14 @@
     "node": ">= 18"
   },
   "peerDependencies": {
-    "@vitus-labs/core": "2.0.0-alpha.24",
+    "@vitus-labs/core": "2.0.0-alpha.26",
     "react": ">= 19"
   },
   "devDependencies": {
-    "@vitus-labs/core": "2.0.0-alpha.25",
-    "@vitus-labs/tools-rolldown": "^1.7.0",
-    "@vitus-labs/tools-storybook": "^1.7.0",
-    "@vitus-labs/tools-typescript": "^1.7.0"
+    "@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"
   },
-  "gitHead": "def2d96c33d27dd520b4d8bd1cf6edc0d556f6e0"
+  "gitHead": "6230c7b4eb1f8fe52bd47275cf72cdcab706cb45"
 }