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

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`.
+ * Uses a reference counter so concurrent locks don't clobber each other.
+ */
+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