@pyreon/hooks 0.11.0 → 0.11.2

package/src/__tests__/useThemeValue.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from "vitest"
+import { useThemeValue } from "../useThemeValue"
+
+// Without a ThemeProvider, useTheme returns the default (empty object {}).
+// So get(theme, path) returns undefined for any path.
+
+describe("useThemeValue", () => {
+  it("returns undefined when no theme values exist", () => {
+    const result = useThemeValue("colors.primary")
+    expect(result).toBeUndefined()
+  })
+})

package/src/__tests__/useThrottledCallback.test.ts

@@ -0,0 +1,56 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+
+// Mock @pyreon/core partially - keep real exports but stub lifecycle hooks
+vi.mock("@pyreon/core", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@pyreon/core")>()
+  return {
+    ...actual,
+    onMount: (fn: () => void) => fn(),
+    onUnmount: (_fn: () => void) => {
+      return undefined
+    },
+  }
+})
+
+import { useThrottledCallback } from "../useThrottledCallback"
+
+describe("useThrottledCallback", () => {
+  beforeEach(() => vi.useFakeTimers())
+  afterEach(() => vi.useRealTimers())
+
+  it("calls immediately on first invocation (leading)", () => {
+    const fn = vi.fn()
+    const throttled = useThrottledCallback(fn, 100)
+
+    throttled("a")
+    expect(fn).toHaveBeenCalledTimes(1)
+    expect(fn).toHaveBeenCalledWith("a")
+  })
+
+  it("throttles subsequent calls", () => {
+    const fn = vi.fn()
+    const throttled = useThrottledCallback(fn, 100)
+
+    throttled("a")
+    throttled("b")
+    throttled("c")
+
+    expect(fn).toHaveBeenCalledTimes(1)
+
+    vi.advanceTimersByTime(100)
+    expect(fn).toHaveBeenCalledTimes(2)
+    expect(fn).toHaveBeenLastCalledWith("c")
+  })
+
+  it("cancel stops pending trailing call", () => {
+    const fn = vi.fn()
+    const throttled = useThrottledCallback(fn, 100)
+
+    throttled("a")
+    throttled("b")
+    throttled.cancel()
+
+    vi.advanceTimersByTime(200)
+    expect(fn).toHaveBeenCalledTimes(1)
+  })
+})

package/src/__tests__/useTimeout.test.ts

@@ -0,0 +1,54 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+import { useTimeout } from "../useTimeout"
+
+// Mock onUnmount since it requires component lifecycle context
+vi.mock("@pyreon/core", () => ({
+  onMount: (fn: () => void) => fn(),
+  onUnmount: (_fn: () => void) => {
+    /* no-op */
+  },
+}))
+
+describe("useTimeout", () => {
+  beforeEach(() => vi.useFakeTimers())
+  afterEach(() => vi.useRealTimers())
+
+  it("calls callback after delay", () => {
+    const fn = vi.fn()
+    useTimeout(fn, 200)
+
+    vi.advanceTimersByTime(200)
+    expect(fn).toHaveBeenCalledTimes(1)
+  })
+
+  it("does not call callback when delay is null", () => {
+    const fn = vi.fn()
+    useTimeout(fn, null)
+
+    vi.advanceTimersByTime(1000)
+    expect(fn).not.toHaveBeenCalled()
+  })
+
+  it("clear() prevents the callback", () => {
+    const fn = vi.fn()
+    const { clear } = useTimeout(fn, 200)
+
+    clear()
+    vi.advanceTimersByTime(500)
+    expect(fn).not.toHaveBeenCalled()
+  })
+
+  it("reset() restarts the timer", () => {
+    const fn = vi.fn()
+    const { reset } = useTimeout(fn, 200)
+
+    vi.advanceTimersByTime(150)
+    reset()
+
+    vi.advanceTimersByTime(150)
+    expect(fn).not.toHaveBeenCalled()
+
+    vi.advanceTimersByTime(50)
+    expect(fn).toHaveBeenCalledTimes(1)
+  })
+})

package/src/__tests__/useToggle.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from "vitest"
+import { useToggle } from "../useToggle"
+
+describe("useToggle", () => {
+  it("defaults to false", () => {
+    const { value } = useToggle()
+    expect(value()).toBe(false)
+  })
+
+  it("respects initial value of true", () => {
+    const { value } = useToggle(true)
+    expect(value()).toBe(true)
+  })
+
+  it("respects initial value of false", () => {
+    const { value } = useToggle(false)
+    expect(value()).toBe(false)
+  })
+
+  it("toggle flips value from false to true", () => {
+    const { value, toggle } = useToggle()
+    toggle()
+    expect(value()).toBe(true)
+  })
+
+  it("toggle flips value from true to false", () => {
+    const { value, toggle } = useToggle(true)
+    toggle()
+    expect(value()).toBe(false)
+  })
+
+  it("toggle flips multiple times", () => {
+    const { value, toggle } = useToggle()
+    toggle()
+    expect(value()).toBe(true)
+    toggle()
+    expect(value()).toBe(false)
+    toggle()
+    expect(value()).toBe(true)
+  })
+
+  it("setTrue sets value to true", () => {
+    const { value, setTrue } = useToggle()
+    setTrue()
+    expect(value()).toBe(true)
+  })
+
+  it("setTrue is idempotent", () => {
+    const { value, setTrue } = useToggle(true)
+    setTrue()
+    expect(value()).toBe(true)
+  })
+
+  it("setFalse sets value to false", () => {
+    const { value, setFalse } = useToggle(true)
+    setFalse()
+    expect(value()).toBe(false)
+  })
+
+  it("setFalse is idempotent", () => {
+    const { value, setFalse } = useToggle(false)
+    setFalse()
+    expect(value()).toBe(false)
+  })
+
+  it("combines toggle, setTrue, and setFalse correctly", () => {
+    const { value, toggle, setTrue, setFalse } = useToggle()
+    expect(value()).toBe(false)
+
+    setTrue()
+    expect(value()).toBe(true)
+
+    setFalse()
+    expect(value()).toBe(false)
+
+    toggle()
+    expect(value()).toBe(true)
+
+    setFalse()
+    expect(value()).toBe(false)
+  })
+})

package/src/__tests__/useUpdateEffect.test.ts

@@ -0,0 +1,48 @@
+import { signal } from "@pyreon/reactivity"
+import { describe, expect, it, vi } from "vitest"
+
+// Mock onUnmount since it requires component lifecycle context
+vi.mock("@pyreon/core", () => ({
+  onMount: (fn: () => void) => fn(),
+  onUnmount: (_fn: () => void) => {
+    /* no-op */
+  },
+}))
+
+import { useUpdateEffect } from "../useUpdateEffect"
+
+describe("useUpdateEffect", () => {
+  it("does not fire on initial setup", () => {
+    const callback = vi.fn()
+    const source = signal(1)
+
+    useUpdateEffect(source, callback)
+    expect(callback).not.toHaveBeenCalled()
+  })
+
+  it("fires when source changes", () => {
+    const callback = vi.fn()
+    const source = signal(1)
+
+    useUpdateEffect(source, callback)
+    expect(callback).not.toHaveBeenCalled()
+
+    source.set(2)
+    expect(callback).toHaveBeenCalledTimes(1)
+    expect(callback).toHaveBeenCalledWith(2, 1)
+  })
+
+  it("fires on each subsequent change", () => {
+    const callback = vi.fn()
+    const source = signal(1)
+
+    useUpdateEffect(source, callback)
+
+    source.set(2)
+    expect(callback).toHaveBeenCalledTimes(1)
+
+    source.set(3)
+    expect(callback).toHaveBeenCalledTimes(2)
+    expect(callback).toHaveBeenCalledWith(3, 2)
+  })
+})

package/src/__tests__/useWindowResize.test.ts

@@ -0,0 +1,139 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+
+let mountCallbacks: Array<() => unknown> = []
+let unmountCallbacks: Array<() => void> = []
+
+vi.mock("@pyreon/core", () => ({
+  onMount: (fn: () => unknown) => {
+    mountCallbacks.push(fn)
+  },
+  onUnmount: (fn: () => void) => {
+    unmountCallbacks.push(fn)
+  },
+}))
+
+import { useWindowResize } from "../useWindowResize"
+
+describe("useWindowResize", () => {
+  const originalInnerWidth = window.innerWidth
+  const originalInnerHeight = window.innerHeight
+
+  beforeEach(() => {
+    mountCallbacks = []
+    unmountCallbacks = []
+    vi.useFakeTimers()
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+    Object.defineProperty(window, "innerWidth", { writable: true, value: originalInnerWidth })
+    Object.defineProperty(window, "innerHeight", { writable: true, value: originalInnerHeight })
+  })
+
+  it("returns initial window dimensions", () => {
+    Object.defineProperty(window, "innerWidth", { writable: true, value: 1024 })
+    Object.defineProperty(window, "innerHeight", { writable: true, value: 768 })
+
+    const size = useWindowResize()
+    expect(size().width).toBe(1024)
+    expect(size().height).toBe(768)
+  })
+
+  it("updates dimensions after resize with throttle", () => {
+    Object.defineProperty(window, "innerWidth", { writable: true, value: 1024 })
+    Object.defineProperty(window, "innerHeight", { writable: true, value: 768 })
+
+    const size = useWindowResize(200)
+    mountCallbacks.forEach((cb) => {
+      cb()
+    })
+
+    // Simulate resize
+    Object.defineProperty(window, "innerWidth", { writable: true, value: 800 })
+    Object.defineProperty(window, "innerHeight", { writable: true, value: 600 })
+    window.dispatchEvent(new Event("resize"))
+
+    // Should not update immediately
+    expect(size().width).toBe(1024)
+
+    // After throttle period
+    vi.advanceTimersByTime(200)
+    expect(size().width).toBe(800)
+    expect(size().height).toBe(600)
+  })
+
+  it("throttles rapid resize events", () => {
+    Object.defineProperty(window, "innerWidth", { writable: true, value: 1024 })
+    Object.defineProperty(window, "innerHeight", { writable: true, value: 768 })
+
+    const size = useWindowResize(100)
+    mountCallbacks.forEach((cb) => {
+      cb()
+    })
+
+    // First resize triggers timer
+    window.dispatchEvent(new Event("resize"))
+
+    // Second resize within throttle window should be ignored
+    Object.defineProperty(window, "innerWidth", { writable: true, value: 500 })
+    Object.defineProperty(window, "innerHeight", { writable: true, value: 400 })
+    window.dispatchEvent(new Event("resize"))
+
+    // After throttle, should use current window dimensions
+    vi.advanceTimersByTime(100)
+    expect(size().width).toBe(500)
+    expect(size().height).toBe(400)
+  })
+
+  it("uses default throttle of 200ms", () => {
+    Object.defineProperty(window, "innerWidth", { writable: true, value: 1024 })
+    Object.defineProperty(window, "innerHeight", { writable: true, value: 768 })
+
+    const size = useWindowResize()
+    mountCallbacks.forEach((cb) => {
+      cb()
+    })
+
+    Object.defineProperty(window, "innerWidth", { writable: true, value: 800 })
+    window.dispatchEvent(new Event("resize"))
+
+    vi.advanceTimersByTime(100)
+    expect(size().width).toBe(1024) // Still throttled
+
+    vi.advanceTimersByTime(100)
+    expect(size().width).toBe(800) // Now updated
+  })
+
+  it("cleans up on unmount", () => {
+    const removeSpy = vi.spyOn(window, "removeEventListener")
+    useWindowResize()
+    mountCallbacks.forEach((cb) => {
+      cb()
+    })
+    unmountCallbacks.forEach((cb) => {
+      cb()
+    })
+
+    expect(removeSpy).toHaveBeenCalledWith("resize", expect.any(Function))
+    removeSpy.mockRestore()
+  })
+
+  it("clears pending timer on unmount", () => {
+    const clearTimeoutSpy = vi.spyOn(globalThis, "clearTimeout")
+    Object.defineProperty(window, "innerWidth", { writable: true, value: 1024 })
+
+    useWindowResize(200)
+    mountCallbacks.forEach((cb) => {
+      cb()
+    })
+
+    // Trigger a resize to start the timer
+    window.dispatchEvent(new Event("resize"))
+
+    unmountCallbacks.forEach((cb) => {
+      cb()
+    })
+    expect(clearTimeoutSpy).toHaveBeenCalled()
+    clearTimeoutSpy.mockRestore()
+  })
+})

package/src/index.ts

@@ -0,0 +1,56 @@
+export type { BreakpointMap } from "./useBreakpoint"
+export { useBreakpoint } from "./useBreakpoint"
+export { useClickOutside } from "./useClickOutside"
+export type { UseClipboardResult } from "./useClipboard"
+export { useClipboard } from "./useClipboard"
+export { useColorScheme } from "./useColorScheme"
+export type { UseControllableState } from "./useControllableState"
+export { useControllableState } from "./useControllableState"
+export type { UseDebouncedCallback } from "./useDebouncedCallback"
+export { useDebouncedCallback } from "./useDebouncedCallback"
+export { useDebouncedValue } from "./useDebouncedValue"
+export type { UseDialogResult } from "./useDialog"
+export { useDialog } from "./useDialog"
+export type { Size } from "./useElementSize"
+export { useElementSize } from "./useElementSize"
+export { useEventListener } from "./useEventListener"
+export type { UseFocusResult } from "./useFocus"
+export { useFocus } from "./useFocus"
+export { useFocusTrap } from "./useFocusTrap"
+export type { UseHoverResult } from "./useHover"
+export { useHover } from "./useHover"
+export type { UseInfiniteScrollOptions, UseInfiniteScrollResult } from "./useInfiniteScroll"
+export { useInfiniteScroll } from "./useInfiniteScroll"
+export { useIntersection } from "./useIntersection"
+export type { UseInterval } from "./useInterval"
+export { useInterval } from "./useInterval"
+export type { UseIsomorphicLayoutEffect } from "./useIsomorphicLayoutEffect"
+export { default as useIsomorphicLayoutEffect } from "./useIsomorphicLayoutEffect"
+export { useKeyboard } from "./useKeyboard"
+export type { UseLatest } from "./useLatest"
+export { useLatest } from "./useLatest"
+export { useMediaQuery } from "./useMediaQuery"
+export type { UseMergedRef } from "./useMergedRef"
+export { useMergedRef } from "./useMergedRef"
+export { useOnline } from "./useOnline"
+export { usePrevious } from "./usePrevious"
+export { useReducedMotion } from "./useReducedMotion"
+export type { UseRootSize } from "./useRootSize"
+export { useRootSize } from "./useRootSize"
+export { useScrollLock } from "./useScrollLock"
+export type { UseSpacing } from "./useSpacing"
+export { useSpacing } from "./useSpacing"
+export type { UseThemeValue } from "./useThemeValue"
+export { useThemeValue } from "./useThemeValue"
+export type { UseThrottledCallback } from "./useThrottledCallback"
+export { useThrottledCallback } from "./useThrottledCallback"
+export type { UseTimeAgoOptions } from "./useTimeAgo"
+export { useTimeAgo } from "./useTimeAgo"
+export type { UseTimeout } from "./useTimeout"
+export { useTimeout } from "./useTimeout"
+export type { UseToggleResult } from "./useToggle"
+export { useToggle } from "./useToggle"
+export type { UseUpdateEffect } from "./useUpdateEffect"
+export { useUpdateEffect } from "./useUpdateEffect"
+export type { WindowSize } from "./useWindowResize"
+export { useWindowResize } from "./useWindowResize"

package/src/useBreakpoint.ts

@@ -0,0 +1,52 @@
+import { onMount, onUnmount } from "@pyreon/core"
+import { signal } from "@pyreon/reactivity"
+
+export type BreakpointMap = Record<string, number>
+
+const defaultBreakpoints: BreakpointMap = {
+  xs: 0,
+  sm: 576,
+  md: 768,
+  lg: 992,
+  xl: 1200,
+}
+
+/**
+ * Return the currently active breakpoint name as a reactive signal.
+ */
+export function useBreakpoint(breakpoints: BreakpointMap = defaultBreakpoints): () => string {
+  const sorted = Object.entries(breakpoints).sort(([, a], [, b]) => a - b)
+  const active = signal(getActive(sorted))
+  let rafId: number | undefined
+
+  function getActive(bps: [string, number][]): string {
+    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 !== undefined) cancelAnimationFrame(rafId)
+    rafId = requestAnimationFrame(() => {
+      const next = getActive(sorted)
+      if (next !== active.peek()) active.set(next)
+    })
+  }
+
+  onMount(() => {
+    window.addEventListener("resize", onResize)
+    return undefined
+  })
+
+  onUnmount(() => {
+    window.removeEventListener("resize", onResize)
+    if (rafId !== undefined) cancelAnimationFrame(rafId)
+  })
+
+  return active
+}

package/src/useClickOutside.ts

@@ -0,0 +1,23 @@
+import { onMount, onUnmount } from "@pyreon/core"
+
+/**
+ * Call handler when a click occurs outside the target element.
+ */
+export function useClickOutside(getEl: () => HTMLElement | null, handler: () => void): void {
+  const listener = (e: Event) => {
+    const el = getEl()
+    if (!el || el.contains(e.target as Node)) return
+    handler()
+  }
+
+  onMount(() => {
+    document.addEventListener("mousedown", listener, true)
+    document.addEventListener("touchstart", listener, true)
+    return undefined
+  })
+
+  onUnmount(() => {
+    document.removeEventListener("mousedown", listener, true)
+    document.removeEventListener("touchstart", listener, true)
+  })
+}

package/src/useClipboard.ts

@@ -0,0 +1,51 @@
+import { onCleanup, signal } from "@pyreon/reactivity"
+
+export interface UseClipboardResult {
+  /** Copy text to clipboard. Returns true on success. */
+  copy: (text: string) => Promise<boolean>
+  /** Whether the last copy succeeded (resets after timeout). */
+  copied: () => boolean
+  /** The last successfully copied text. */
+  text: () => string
+}
+
+/**
+ * Reactive clipboard access — copy text and track copied state.
+ *
+ * @param options.timeout - ms before `copied` resets to false (default: 2000)
+ *
+ * @example
+ * ```tsx
+ * const { copy, copied } = useClipboard()
+ *
+ * <button onClick={() => copy("hello")}>
+ *   {() => copied() ? "Copied!" : "Copy"}
+ * </button>
+ * ```
+ */
+export function useClipboard(options?: { timeout?: number }): UseClipboardResult {
+  const timeout = options?.timeout ?? 2000
+  const copied = signal(false)
+  const text = signal("")
+  let timer: ReturnType<typeof setTimeout> | undefined
+
+  const copy = async (value: string): Promise<boolean> => {
+    try {
+      await navigator.clipboard.writeText(value)
+      text.set(value)
+      copied.set(true)
+      if (timer) clearTimeout(timer)
+      timer = setTimeout(() => copied.set(false), timeout)
+      return true
+    } catch {
+      copied.set(false)
+      return false
+    }
+  }
+
+  onCleanup(() => {
+    if (timer) clearTimeout(timer)
+  })
+
+  return { copy, copied, text }
+}

package/src/useColorScheme.ts

@@ -0,0 +1,10 @@
+import { computed } from "@pyreon/reactivity"
+import { useMediaQuery } from "./useMediaQuery"
+
+/**
+ * Returns the OS color scheme preference as 'light' or 'dark'.
+ */
+export function useColorScheme(): () => "light" | "dark" {
+  const prefersDark = useMediaQuery("(prefers-color-scheme: dark)")
+  return computed(() => (prefersDark() ? "dark" : "light"))
+}

package/src/useControllableState.ts

@@ -0,0 +1,39 @@
+import { signal } from "@pyreon/reactivity"
+
+type UseControllableStateOptions<T> = {
+  value?: T | undefined
+  defaultValue: T
+  onChange?: ((value: T) => void) | undefined
+}
+
+export 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.
+ *
+ * Returns [getter, setter] where getter is a reactive function.
+ */
+export const useControllableState: UseControllableState = ({ value, defaultValue, onChange }) => {
+  const internal = signal(defaultValue)
+  const onChangeFn = onChange
+
+  const isControlled = value !== undefined
+
+  const getter = (): any => (isControlled ? value : internal())
+
+  const setValue = (next: any) => {
+    const current = isControlled ? value : internal()
+    const nextValue = typeof next === "function" ? next(current) : next
+    if (!isControlled) internal.set(nextValue)
+    onChangeFn?.(nextValue)
+  }
+
+  return [getter, setValue]
+}
+
+export default useControllableState

package/src/useDebouncedCallback.ts

@@ -0,0 +1,57 @@
+import { onUnmount } from "@pyreon/core"
+
+type DebouncedFn<T extends (...args: any[]) => any> = {
+  (...args: Parameters<T>): void
+  cancel: () => void
+  flush: () => void
+}
+
+export type UseDebouncedCallback = <T extends (...args: any[]) => any>(
+  callback: T,
+  delay: number,
+) => DebouncedFn<T>
+
+/**
+ * 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.
+ */
+export const useDebouncedCallback: UseDebouncedCallback = (callback, delay) => {
+  const currentCallback = callback
+  let timer: ReturnType<typeof setTimeout> | null = null
+  let lastArgs: any[] | null = null
+
+  const cancel = () => {
+    if (timer != null) {
+      clearTimeout(timer)
+      timer = null
+    }
+    lastArgs = null
+  }
+
+  const flush = () => {
+    if (timer != null && lastArgs != null) {
+      clearTimeout(timer)
+      timer = null
+      currentCallback(...lastArgs)
+      lastArgs = null
+    }
+  }
+
+  const debounced = (...args: any[]) => {
+    lastArgs = args
+    if (timer != null) clearTimeout(timer)
+    timer = setTimeout(() => {
+      timer = null
+      currentCallback(...args)
+      lastArgs = null
+    }, delay)
+  }
+
+  onUnmount(() => cancel())
+
+  return Object.assign(debounced, { cancel, flush }) as DebouncedFn<typeof callback>
+}
+
+export default useDebouncedCallback