@pyreon/hooks 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-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.

package/README.md

@@ -0,0 +1,196 @@
+# @pyreon/hooks
+
+16 signal-based reactive utilities for Pyreon UI interactions, DOM observation, accessibility, and theming.
+
+All hooks use `signal()` for internal state and return reactive getters. Components are plain functions that run once — no `useCallback`/`useMemo` needed.
+
+## Installation
+
+```bash
+bun add @pyreon/hooks
+```
+
+## Hooks
+
+### Interaction
+
+#### useHover
+
+Tracks hover state via mouse enter/leave events.
+
+```ts
+import { useHover } from '@pyreon/hooks'
+
+const { hover, onMouseEnter, onMouseLeave } = useHover()
+```
+
+#### useFocus
+
+Tracks focus state via focus/blur events.
+
+```ts
+import { useFocus } from '@pyreon/hooks'
+
+const { focused, onFocus, onBlur } = useFocus()
+```
+
+#### useClickOutside
+
+Calls handler when a click occurs outside the referenced element.
+
+```ts
+import { useClickOutside } from '@pyreon/hooks'
+
+useClickOutside(elementRef, () => setOpen(false))
+```
+
+#### useScrollLock
+
+Locks page scroll by setting `overflow: hidden` on `document.body`.
+
+```ts
+import { useScrollLock } from '@pyreon/hooks'
+
+useScrollLock(isModalOpen)
+```
+
+#### useKeyboard
+
+Listens for a specific keyboard key.
+
+```ts
+import { useKeyboard } from '@pyreon/hooks'
+
+useKeyboard('Escape', () => setOpen(false))
+```
+
+#### useFocusTrap
+
+Traps Tab/Shift+Tab focus within a container. Essential for modals and dialogs.
+
+```ts
+import { useFocusTrap } from '@pyreon/hooks'
+
+useFocusTrap(containerRef, isOpen)
+```
+
+### DOM & Observers
+
+#### useElementSize
+
+Tracks element `width` and `height` via `ResizeObserver`.
+
+```ts
+import { useElementSize } from '@pyreon/hooks'
+
+const { ref, width, height } = useElementSize()
+```
+
+#### useIntersection
+
+`IntersectionObserver` wrapper for visibility detection.
+
+```ts
+import { useIntersection } from '@pyreon/hooks'
+
+const { ref, entry } = useIntersection({ threshold: 0.5 })
+const isVisible = entry?.isIntersecting
+```
+
+#### useWindowResize
+
+Tracks viewport dimensions with throttled updates.
+
+```ts
+import { useWindowResize } from '@pyreon/hooks'
+
+const { width, height } = useWindowResize({ throttleDelay: 300 })
+```
+
+### Responsive
+
+#### useMediaQuery
+
+Subscribes to a CSS media query and returns whether it matches.
+
+```ts
+import { useMediaQuery } from '@pyreon/hooks'
+
+const isDesktop = useMediaQuery('(min-width: 1024px)')
+```
+
+#### useBreakpoint
+
+Returns the currently active breakpoint name from the theme context.
+
+```ts
+import { useBreakpoint } from '@pyreon/hooks'
+
+const bp = useBreakpoint() // "xs" | "sm" | "md" | "lg" | "xl" | undefined
+```
+
+#### useColorScheme
+
+Returns the user's preferred color scheme. Pairs with rocketstyle's `mode`.
+
+```ts
+import { useColorScheme } from '@pyreon/hooks'
+
+const scheme = useColorScheme() // "light" | "dark"
+```
+
+#### useReducedMotion
+
+Returns `true` when the user prefers reduced motion.
+
+```ts
+import { useReducedMotion } from '@pyreon/hooks'
+
+const reduced = useReducedMotion()
+const duration = reduced ? 0 : 300
+```
+
+### State
+
+#### useToggle
+
+Boolean state with `toggle`, `setTrue`, and `setFalse` helpers.
+
+```ts
+import { useToggle } from '@pyreon/hooks'
+
+const { value, toggle, setTrue, setFalse } = useToggle(false)
+```
+
+#### usePrevious
+
+Returns the value from the previous evaluation.
+
+```ts
+import { usePrevious } from '@pyreon/hooks'
+
+const prev = usePrevious(count)
+```
+
+#### useDebouncedValue
+
+Returns a debounced version of the value that only updates after `delay` ms of inactivity.
+
+```ts
+import { useDebouncedValue } from '@pyreon/hooks'
+
+const debouncedSearch = useDebouncedValue(searchTerm, 300)
+```
+
+## Peer Dependencies
+
+| Package | Version |
+| ------- | ------- |
+| @pyreon/core | >= 0.0.1 |
+| @pyreon/reactivity | >= 0.0.1 |
+| @pyreon/styler | >= 0.0.1 |
+| @pyreon/ui-core | >= 0.0.1 |
+
+## License
+
+MIT

package/lib/index.d.ts

@@ -0,0 +1,434 @@
+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
+
+/**
+* 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.
+*/
+
+//#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
+
+/**
+* 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).
+*/
+
+//#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.
+*/
+
+//#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.
+*/
+
+/**
+* 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"
+* ```
+*/
+
+//#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)
+*/
+
+//#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.d.ts.map