@pyreon/hooks 0.1.1 → 0.2.0

package/lib/index.d.ts

@@ -1,434 +1,312 @@
-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
+import { onMount } from "@pyreon/core";
 
+//#region src/useBreakpoint.d.ts
+type BreakpointMap = Record<string, number>;
 /**
-* 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;
-}
-
+ * Return the currently active breakpoint name as a reactive signal.
+ */
+declare function useBreakpoint(breakpoints?: BreakpointMap): () => string;
 //#endregion
-//#region src/useClickOutside.ts
+//#region src/useClickOutside.d.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);
-  });
-}
-
+ * Call handler when a click occurs outside the target element.
+ */
+declare function useClickOutside(getEl: () => HTMLElement | null, handler: () => void): void;
 //#endregion
-//#region src/useMediaQuery.ts
+//#region src/useColorScheme.d.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;
-}
-
+ * Returns the OS color scheme preference as 'light' or 'dark'.
+ */
+declare function useColorScheme(): () => "light" | "dark";
 //#endregion
-//#region src/useColorScheme.ts
+//#region src/useControllableState.d.ts
+type UseControllableStateOptions<T> = {
+  value?: T | undefined;
+  defaultValue: T;
+  onChange?: ((value: T) => void) | undefined;
+};
+type UseControllableState = <T>(options: UseControllableStateOptions<T>) => [() => T, (next: T | ((prev: T) => T)) => void];
 /**
-* Returns the OS color scheme preference as 'light' or 'dark'.
-*/
-function useColorScheme() {
-  const prefersDark = useMediaQuery("(prefers-color-scheme: dark)");
-  return computed(() => prefersDark() ? "dark" : "light");
-}
-
+ * 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.
+ */
+declare const useControllableState: UseControllableState;
 //#endregion
-//#region src/useControllableState.ts
+//#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>;
 /**
-* 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.
-*/
-
+ * 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.
+ */
+declare const useDebouncedCallback: UseDebouncedCallback;
 //#endregion
-//#region src/useDebouncedValue.ts
+//#region src/useDebouncedValue.d.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;
-}
-
+ * Return a debounced version of a reactive value.
+ */
+declare function useDebouncedValue<T>(getter: () => T, delayMs: number): () => T;
 //#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;
+//#region src/useElementSize.d.ts
+interface Size {
+  width: number;
+  height: number;
 }
-
-//#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)
-    }
+ * Observe element dimensions reactively via ResizeObserver.
+ */
+declare function useElementSize(getEl: () => HTMLElement | null): () => Size;
+//#endregion
+//#region src/useFocus.d.ts
+interface UseFocusResult {
+  focused: () => boolean;
+  props: {
+    onFocus: () => void;
+    onBlur: () => void;
   };
 }
-
+/**
+ * Track focus state reactively.
+ */
+declare function useFocus(): UseFocusResult;
 //#endregion
-//#region src/useFocusTrap.ts
-
+//#region src/useFocusTrap.d.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();
-    }
+ * Trap Tab/Shift+Tab focus within a container element.
+ */
+declare function useFocusTrap(getEl: () => HTMLElement | null): void;
+//#endregion
+//#region src/useHover.d.ts
+interface UseHoverResult {
+  /** Reactive boolean — true when element is hovered */
+  hovered: () => boolean;
+  /** Props to spread onto the element */
+  props: {
+    onMouseEnter: () => void;
+    onMouseLeave: () => void;
   };
-  onMount(() => {
-    document.addEventListener("keydown", listener);
-  });
-  onUnmount(() => {
-    document.removeEventListener("keydown", listener);
-  });
 }
-
+/**
+ * Track hover state reactively.
+ *
+ * @example
+ * const { hovered, props } = useHover()
+ * h('div', { ...props, class: () => hovered() ? 'active' : '' })
+ */
+declare function useHover(): UseHoverResult;
 //#endregion
-//#region src/useHover.ts
+//#region src/useIntersection.d.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)
-    }
-  };
-}
-
+ * Observe element intersection reactively.
+ */
+declare function useIntersection(getEl: () => HTMLElement | null, options?: IntersectionObserverInit): () => IntersectionObserverEntry | null;
 //#endregion
-//#region src/useIntersection.ts
+//#region src/useInterval.d.ts
+type UseInterval = (callback: () => void, delay: number | null) => void;
 /**
-* 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;
-}
-
+ * 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/useInterval.ts
+//#region src/useIsomorphicLayoutEffect.d.ts
 /**
-* Declarative `setInterval` with auto-cleanup.
-* Pass `null` as `delay` to pause the interval.
-* Always calls the latest callback (no stale closures).
-*/
-
+ * In Pyreon there is no SSR warning distinction between effect and
+ * layout-effect as there is in React.
+ *
+ * On the client `onMount` fires synchronously after the component is
+ * mounted (similar to useLayoutEffect). On the server `effect` is a
+ * no-op. This export provides the appropriate primitive for each env.
+ *
+ * Consumers that need layout-timing should use `onMount` directly.
+ * This hook is provided for API parity with the original library.
+ */
+type UseIsomorphicLayoutEffect = typeof onMount;
+declare const useIsomorphicLayoutEffect: UseIsomorphicLayoutEffect;
 //#endregion
-//#region src/useKeyboard.ts
+//#region src/useKeyboard.d.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);
-  });
-}
-
+ * Listen for a specific key press.
+ */
+declare function useKeyboard(key: string, handler: (event: KeyboardEvent) => void, options?: {
+  event?: "keydown" | "keyup";
+  target?: EventTarget;
+}): void;
 //#endregion
-//#region src/useLatest.ts
+//#region src/useLatest.d.ts
+type UseLatest = <T>(value: T) => {
+  readonly current: T;
+};
 /**
-* 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.
-*/
-
+ * 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.
+ */
+declare const useLatest: UseLatest;
 //#endregion
-//#region src/usePrevious.ts
+//#region src/useMediaQuery.d.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;
-}
-
+ * Subscribe to a CSS media query, returns a reactive boolean.
+ */
+declare function useMediaQuery(query: string): () => boolean;
 //#endregion
-//#region src/useReducedMotion.ts
+//#region src/useMergedRef.d.ts
+type RefCallback<T> = (node: T | null) => void;
+type RefObject<T> = {
+  current: T | null;
+};
+type Ref<T> = RefCallback<T> | RefObject<T>;
+type UseMergedRef = <T>(...refs: (Ref<T> | undefined)[]) => (node: T | null) => void;
 /**
-* Returns true when the user prefers reduced motion.
-*/
-function useReducedMotion() {
-  return useMediaQuery("(prefers-reduced-motion: reduce)");
-}
-
+ * Merges multiple refs (callback or object) into a single callback ref.
+ * Handles undefined, callback refs, and object refs with `.current`.
+ */
+declare const useMergedRef: <T>(...refs: (Ref<T> | undefined)[]) => ((node: T | null) => void);
 //#endregion
-//#region src/useRootSize.ts
+//#region src/usePrevious.d.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.
-*/
-
+ * Track the previous value of a reactive getter.
+ * Returns undefined on first access.
+ */
+declare function usePrevious<T>(getter: () => T): () => T | undefined;
+//#endregion
+//#region src/useReducedMotion.d.ts
 /**
-* 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
-  };
-}
-
+ * Returns true when the user prefers reduced motion.
+ */
+declare function useReducedMotion(): () => boolean;
 //#endregion
-//#region src/useSpacing.ts
+//#region src/useRootSize.d.ts
+type RootSizeResult = {
+  rootSize: number;
+  pxToRem: (px: number) => string;
+  remToPx: (rem: number) => number;
+};
+type UseRootSize = () => RootSizeResult;
 /**
-* 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"
-* ```
-*/
-
+ * Returns `rootSize` from the theme context along with
+ * `pxToRem` and `remToPx` conversion utilities.
+ *
+ * Defaults to `16` when no rootSize is set in the theme.
+ */
+declare const useRootSize: UseRootSize;
 //#endregion
-//#region src/useToggle.ts
+//#region src/useScrollLock.d.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)
-  };
-}
-
+ * Lock page scroll. Uses reference counting for concurrent locks.
+ * Returns an unlock function.
+ */
+declare function useScrollLock(): {
+  lock: () => void;
+  unlock: () => void;
+};
 //#endregion
-//#region src/useUpdateEffect.ts
+//#region src/useSpacing.d.ts
+type UseSpacing = (base?: number | undefined) => (multiplier: number) => string;
 /**
-* 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)
-*/
-
+ * 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 throttled version of the callback.
+ * Uses `throttle` from `@pyreon/ui-core`.
+ * Always calls the latest callback (no stale closures).
+ * Cleans up on unmount.
+ */
+declare const useThrottledCallback: UseThrottledCallback;
 //#endregion
-//#region src/useWindowResize.ts
+//#region src/useTimeout.d.ts
+type UseTimeout = (callback: () => void, delay: number | null) => {
+  reset: () => void;
+  clear: () => void;
+};
 /**
-* 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;
+ * 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
+interface UseToggleResult {
+  value: () => boolean;
+  toggle: () => void;
+  setTrue: () => void;
+  setFalse: () => void;
 }
-
+/**
+ * Simple boolean toggle.
+ */
+declare function useToggle(initial?: boolean): UseToggleResult;
+//#endregion
+//#region src/useUpdateEffect.d.ts
+type UseUpdateEffect = <T>(source: () => T, callback: (newVal: T, oldVal: T | undefined) => undefined | (() => void)) => void;
+/**
+ * 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)
+ */
+declare const useUpdateEffect: UseUpdateEffect;
+//#endregion
+//#region src/useWindowResize.d.ts
+interface WindowSize {
+  width: number;
+  height: number;
+}
+/**
+ * Track window dimensions reactively with throttling.
+ */
+declare function useWindowResize(throttleMs?: number): () => WindowSize;
 //#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
+export { type BreakpointMap, type Size, type UseControllableState, type UseDebouncedCallback, type UseFocusResult, type UseHoverResult, type UseInterval, type UseIsomorphicLayoutEffect, type UseLatest, type UseMergedRef, type UseRootSize, type UseSpacing, type UseThemeValue, type UseThrottledCallback, type UseTimeout, type UseToggleResult, type UseUpdateEffect, type WindowSize, 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/hooks",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/pyreon/ui-system",
@@ -43,8 +43,8 @@
   "peerDependencies": {
     "@pyreon/core": ">=0.4.0 <1.0.0",
     "@pyreon/reactivity": ">=0.4.0 <1.0.0",
-    "@pyreon/styler": ">=0.1.1",
-    "@pyreon/ui-core": ">=0.1.1"
+    "@pyreon/styler": ">=0.2.0",
+    "@pyreon/ui-core": ">=0.2.0"
   },
   "devDependencies": {
     "@vitus-labs/tools-rolldown": "^1.15.3",