@pyreon/hooks 0.11.1 → 0.11.3

package/src/useDebouncedValue.ts

@@ -0,0 +1,24 @@
+import { onUnmount } from "@pyreon/core"
+import { effect, signal } from "@pyreon/reactivity"
+
+/**
+ * Return a debounced version of a reactive value.
+ */
+export function useDebouncedValue<T>(getter: () => T, delayMs: number): () => T {
+  const debounced = signal<T>(getter())
+  let timer: ReturnType<typeof setTimeout> | undefined
+
+  effect(() => {
+    const val = getter()
+    if (timer !== undefined) clearTimeout(timer)
+    timer = setTimeout(() => {
+      debounced.set(val)
+    }, delayMs)
+  })
+
+  onUnmount(() => {
+    if (timer !== undefined) clearTimeout(timer)
+  })
+
+  return debounced
+}

package/src/useDialog.ts

@@ -0,0 +1,83 @@
+import { onCleanup, signal } from "@pyreon/reactivity"
+
+export interface UseDialogResult {
+  /** Whether the dialog is currently open. */
+  open: () => boolean
+  /** Open the dialog. */
+  show: () => void
+  /** Open as modal (with backdrop, traps focus). */
+  showModal: () => void
+  /** Close the dialog. */
+  close: () => void
+  /** Toggle open/closed state. */
+  toggle: () => void
+  /** Ref callback — pass to `ref` prop on a `<dialog>` element. */
+  ref: (el: HTMLDialogElement) => void
+}
+
+/**
+ * Signal-driven dialog management for the native `<dialog>` element.
+ *
+ * @example
+ * ```tsx
+ * const dialog = useDialog()
+ *
+ * <button onClick={dialog.showModal}>Open</button>
+ * <dialog ref={dialog.ref}>
+ *   <p>Modal content</p>
+ *   <button onClick={dialog.close}>Close</button>
+ * </dialog>
+ * ```
+ */
+export function useDialog(options?: { onClose?: () => void }): UseDialogResult {
+  const open = signal(false)
+  let dialogEl: HTMLDialogElement | null = null
+  let closeHandler: (() => void) | null = null
+
+  const show = () => {
+    dialogEl?.show()
+    open.set(true)
+  }
+
+  const showModal = () => {
+    dialogEl?.showModal()
+    open.set(true)
+  }
+
+  const close = () => {
+    dialogEl?.close()
+    open.set(false)
+  }
+
+  const toggle = () => {
+    if (open()) close()
+    else showModal()
+  }
+
+  // Attach the close listener in the ref callback — guaranteed to have
+  // the element. onMount fires at the same time as ref in Pyreon, but
+  // ref is more reliable since it's called with the actual element.
+  const ref = (el: HTMLDialogElement) => {
+    // Clean up previous element if ref is called again
+    if (dialogEl && closeHandler) {
+      dialogEl.removeEventListener("close", closeHandler)
+    }
+
+    dialogEl = el
+
+    closeHandler = () => {
+      open.set(false)
+      options?.onClose?.()
+    }
+
+    el.addEventListener("close", closeHandler)
+  }
+
+  onCleanup(() => {
+    if (dialogEl && closeHandler) {
+      dialogEl.removeEventListener("close", closeHandler)
+    }
+  })
+
+  return { open, show, showModal, close, toggle, ref }
+}

package/src/useElementSize.ts

@@ -0,0 +1,38 @@
+import { onMount, onUnmount } from "@pyreon/core"
+import { signal } from "@pyreon/reactivity"
+
+export interface Size {
+  width: number
+  height: number
+}
+
+/**
+ * Observe element dimensions reactively via ResizeObserver.
+ */
+export function useElementSize(getEl: () => HTMLElement | null): () => Size {
+  const size = signal<Size>({ width: 0, height: 0 })
+  let observer: ResizeObserver | undefined
+
+  onMount(() => {
+    const el = getEl()
+    if (!el) return undefined
+
+    observer = new ResizeObserver(([entry]) => {
+      if (!entry) return
+      const { width, height } = entry.contentRect
+      size.set({ width, height })
+    })
+    observer.observe(el)
+
+    // Initial measurement
+    const rect = el.getBoundingClientRect()
+    size.set({ width: rect.width, height: rect.height })
+    return undefined
+  })
+
+  onUnmount(() => {
+    observer?.disconnect()
+  })
+
+  return size
+}

package/src/useEventListener.ts

@@ -0,0 +1,31 @@
+import { onCleanup } from "@pyreon/reactivity"
+
+/**
+ * Attach an event listener with automatic cleanup on unmount.
+ * Works with Window, Document, HTMLElement, or any EventTarget.
+ *
+ * @example
+ * ```tsx
+ * useEventListener("keydown", (e) => {
+ *   if (e.key === "Escape") close()
+ * })
+ *
+ * useEventListener("scroll", handleScroll, { passive: true })
+ *
+ * // On a specific element:
+ * useEventListener("click", handler, {}, () => buttonRef.current)
+ * ```
+ */
+export function useEventListener<K extends keyof WindowEventMap>(
+  event: K,
+  handler: (e: WindowEventMap[K]) => void,
+  options?: boolean | AddEventListenerOptions,
+  target?: () => EventTarget | null | undefined,
+): void {
+  const isBrowser = typeof window !== "undefined"
+  if (!isBrowser) return
+
+  const el = target?.() ?? window
+  el.addEventListener(event, handler as EventListener, options)
+  onCleanup(() => el.removeEventListener(event, handler as EventListener, options))
+}

package/src/useFocus.ts

@@ -0,0 +1,24 @@
+import { signal } from "@pyreon/reactivity"
+
+export interface UseFocusResult {
+  focused: () => boolean
+  props: {
+    onFocus: () => void
+    onBlur: () => void
+  }
+}
+
+/**
+ * Track focus state reactively.
+ */
+export function useFocus(): UseFocusResult {
+  const focused = signal(false)
+
+  return {
+    focused,
+    props: {
+      onFocus: () => focused.set(true),
+      onBlur: () => focused.set(false),
+    },
+  }
+}

package/src/useFocusTrap.ts

@@ -0,0 +1,42 @@
+import { onMount, onUnmount } from "@pyreon/core"
+
+const FOCUSABLE =
+  'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])'
+
+/**
+ * Trap Tab/Shift+Tab focus within a container element.
+ */
+export function useFocusTrap(getEl: () => HTMLElement | null): void {
+  const listener = (e: KeyboardEvent) => {
+    if (e.key !== "Tab") return
+    const el = getEl()
+    if (!el) return
+
+    const focusable = Array.from(el.querySelectorAll<HTMLElement>(FOCUSABLE))
+    if (focusable.length === 0) return
+
+    const first = focusable[0] as HTMLElement
+    const last = focusable[focusable.length - 1] as HTMLElement
+
+    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)
+    return undefined
+  })
+
+  onUnmount(() => {
+    document.removeEventListener("keydown", listener)
+  })
+}

package/src/useHover.ts

@@ -0,0 +1,30 @@
+import { signal } from "@pyreon/reactivity"
+
+export interface UseHoverResult {
+  /** Reactive boolean — true when element is hovered */
+  hovered: () => boolean
+  /** Props to spread onto the element */
+  props: {
+    onMouseEnter: () => void
+    onMouseLeave: () => void
+  }
+}
+
+/**
+ * Track hover state reactively.
+ *
+ * @example
+ * const { hovered, props } = useHover()
+ * h('div', { ...props, class: () => hovered() ? 'active' : '' })
+ */
+export function useHover(): UseHoverResult {
+  const hovered = signal(false)
+
+  return {
+    hovered,
+    props: {
+      onMouseEnter: () => hovered.set(true),
+      onMouseLeave: () => hovered.set(false),
+    },
+  }
+}

package/src/useInfiniteScroll.ts

@@ -0,0 +1,115 @@
+import { onCleanup, signal } from "@pyreon/reactivity"
+
+export interface UseInfiniteScrollOptions {
+  /** Distance from bottom (px) to trigger load. Default: 100 */
+  threshold?: number
+  /** Whether loading is in progress (prevents duplicate calls). */
+  loading?: () => boolean
+  /** Whether there's more data to load. Default: true */
+  hasMore?: () => boolean
+  /** Scroll direction. Default: "down" */
+  direction?: "up" | "down"
+}
+
+export interface UseInfiniteScrollResult {
+  /** Attach to the scroll container element. */
+  ref: (el: HTMLElement | null) => void
+  /** Whether the sentinel is currently visible. */
+  triggered: () => boolean
+}
+
+/**
+ * Signal-driven infinite scroll using IntersectionObserver.
+ * Calls `onLoadMore` when the user scrolls near the end of the container.
+ *
+ * @example
+ * ```tsx
+ * const items = signal<Item[]>([])
+ * const loading = signal(false)
+ * const hasMore = signal(true)
+ *
+ * const { ref } = useInfiniteScroll(() => {
+ *   loading.set(true)
+ *   const next = await fetchMore()
+ *   items.update(prev => [...prev, ...next])
+ *   hasMore.set(next.length > 0)
+ *   loading.set(false)
+ * }, { loading, hasMore })
+ *
+ * <div ref={ref} style={{ overflowY: "auto", height: "400px" }}>
+ *   <For each={items()} by={i => i.id}>
+ *     {item => <div>{item.name}</div>}
+ *   </For>
+ * </div>
+ * ```
+ */
+export function useInfiniteScroll(
+  onLoadMore: () => void | Promise<void>,
+  options?: UseInfiniteScrollOptions,
+): UseInfiniteScrollResult {
+  const threshold = options?.threshold ?? 100
+  const direction = options?.direction ?? "down"
+  const triggered = signal(false)
+  let observer: IntersectionObserver | null = null
+  let sentinel: HTMLDivElement | null = null
+  let containerEl: HTMLElement | null = null
+
+  const handleIntersect = (entries: IntersectionObserverEntry[]) => {
+    const entry = entries[0]
+    if (!entry) return
+
+    triggered.set(entry.isIntersecting)
+
+    if (entry.isIntersecting) {
+      if (options?.loading?.()) return
+      if (options?.hasMore && !options.hasMore()) return
+      onLoadMore()
+    }
+  }
+
+  const setup = (el: HTMLElement) => {
+    cleanup()
+    containerEl = el
+
+    // Create an invisible sentinel element at the scroll boundary
+    sentinel = document.createElement("div")
+    sentinel.style.height = "1px"
+    sentinel.style.width = "100%"
+    sentinel.style.pointerEvents = "none"
+    sentinel.setAttribute("aria-hidden", "true")
+
+    if (direction === "down") {
+      el.appendChild(sentinel)
+    } else {
+      el.insertBefore(sentinel, el.firstChild)
+    }
+
+    observer = new IntersectionObserver(handleIntersect, {
+      root: el,
+      rootMargin:
+        direction === "down" ? `0px 0px ${threshold}px 0px` : `${threshold}px 0px 0px 0px`,
+      threshold: 0,
+    })
+    observer.observe(sentinel)
+  }
+
+  const cleanup = () => {
+    if (observer) {
+      observer.disconnect()
+      observer = null
+    }
+    if (sentinel && containerEl) {
+      sentinel.remove()
+      sentinel = null
+    }
+  }
+
+  const ref = (el: HTMLElement | null) => {
+    if (el) setup(el)
+    else cleanup()
+  }
+
+  onCleanup(cleanup)
+
+  return { ref, triggered }
+}

package/src/useIntersection.ts

@@ -0,0 +1,30 @@
+import { onMount, onUnmount } from "@pyreon/core"
+import { signal } from "@pyreon/reactivity"
+
+/**
+ * Observe element intersection reactively.
+ */
+export function useIntersection(
+  getEl: () => HTMLElement | null,
+  options?: IntersectionObserverInit,
+): () => IntersectionObserverEntry | null {
+  const entry = signal<IntersectionObserverEntry | null>(null)
+  let observer: IntersectionObserver | undefined
+
+  onMount(() => {
+    const el = getEl()
+    if (!el) return undefined
+
+    observer = new IntersectionObserver(([e]) => {
+      if (e) entry.set(e)
+    }, options)
+    observer.observe(el)
+    return undefined
+  })
+
+  onUnmount(() => {
+    observer?.disconnect()
+  })
+
+  return entry
+}

package/src/useInterval.ts

@@ -0,0 +1,31 @@
+import { onUnmount } from "@pyreon/core"
+
+export 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).
+ */
+export const useInterval: UseInterval = (callback, delay) => {
+  const currentCallback = callback
+  let intervalId: ReturnType<typeof setInterval> | null = null
+
+  const start = () => {
+    if (delay === null) return
+    intervalId = setInterval(() => currentCallback(), delay)
+  }
+
+  const stop = () => {
+    if (intervalId != null) {
+      clearInterval(intervalId)
+      intervalId = null
+    }
+  }
+
+  start()
+
+  onUnmount(() => stop())
+}
+
+export default useInterval

package/src/useIsomorphicLayoutEffect.ts

@@ -0,0 +1,19 @@
+import { onMount } from "@pyreon/core"
+
+/**
+ * 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.
+ */
+export type UseIsomorphicLayoutEffect = typeof onMount
+
+const useIsomorphicLayoutEffect: UseIsomorphicLayoutEffect =
+  typeof window !== "undefined" ? onMount : onMount
+
+export default useIsomorphicLayoutEffect

package/src/useKeyboard.ts

@@ -0,0 +1,28 @@
+import { onMount, onUnmount } from "@pyreon/core"
+
+/**
+ * Listen for a specific key press.
+ */
+export function useKeyboard(
+  key: string,
+  handler: (event: KeyboardEvent) => void,
+  options?: { event?: "keydown" | "keyup"; target?: EventTarget },
+): void {
+  const eventName = options?.event ?? "keydown"
+
+  const listener = (e: Event) => {
+    const ke = e as KeyboardEvent
+    if (ke.key === key) handler(ke)
+  }
+
+  onMount(() => {
+    const target = options?.target ?? document
+    target.addEventListener(eventName, listener)
+    return undefined
+  })
+
+  onUnmount(() => {
+    const target = options?.target ?? document
+    target.removeEventListener(eventName, listener)
+  })
+}

package/src/useLatest.ts

@@ -0,0 +1,17 @@
+export 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.
+ */
+export const useLatest: UseLatest = <T>(value: T) => {
+  const ref = { current: value }
+  return ref
+}
+
+export default useLatest

package/src/useMediaQuery.ts

@@ -0,0 +1,27 @@
+import { onMount, onUnmount } from "@pyreon/core"
+import { signal } from "@pyreon/reactivity"
+
+/**
+ * Subscribe to a CSS media query, returns a reactive boolean.
+ */
+export function useMediaQuery(query: string): () => boolean {
+  const matches = signal(false)
+  let mql: MediaQueryList | undefined
+
+  const onChange = (e: MediaQueryListEvent) => {
+    matches.set(e.matches)
+  }
+
+  onMount(() => {
+    mql = window.matchMedia(query)
+    matches.set(mql.matches)
+    mql.addEventListener("change", onChange)
+    return undefined
+  })
+
+  onUnmount(() => {
+    mql?.removeEventListener("change", onChange)
+  })
+
+  return matches
+}

package/src/useMergedRef.ts

@@ -0,0 +1,24 @@
+type RefCallback<T> = (node: T | null) => void
+type RefObject<T> = { current: T | null }
+type Ref<T> = RefCallback<T> | RefObject<T>
+
+export type UseMergedRef = <T>(...refs: (Ref<T> | undefined)[]) => (node: T | null) => void
+
+/**
+ * Merges multiple refs (callback or object) into a single callback ref.
+ * Handles undefined, callback refs, and object refs with `.current`.
+ */
+export const useMergedRef = <T>(...refs: (Ref<T> | undefined)[]): ((node: T | null) => void) => {
+  return (node: T | null) => {
+    for (const ref of refs) {
+      if (!ref) continue
+      if (typeof ref === "function") {
+        ref(node)
+      } else {
+        ;(ref as RefObject<unknown>).current = node
+      }
+    }
+  }
+}
+
+export default useMergedRef

package/src/useOnline.ts

@@ -0,0 +1,31 @@
+import { onCleanup, signal } from "@pyreon/reactivity"
+
+/**
+ * Reactive online/offline status.
+ * Tracks `navigator.onLine` and updates on connectivity changes.
+ *
+ * @example
+ * ```tsx
+ * const online = useOnline()
+ * <Show when={!online()} fallback={<App />}>
+ *   <OfflineBanner />
+ * </Show>
+ * ```
+ */
+export function useOnline(): () => boolean {
+  const isBrowser = typeof window !== "undefined"
+  const online = signal(isBrowser ? navigator.onLine : true)
+
+  if (isBrowser) {
+    const setOnline = () => online.set(true)
+    const setOffline = () => online.set(false)
+    window.addEventListener("online", setOnline)
+    window.addEventListener("offline", setOffline)
+    onCleanup(() => {
+      window.removeEventListener("online", setOnline)
+      window.removeEventListener("offline", setOffline)
+    })
+  }
+
+  return online
+}

package/src/usePrevious.ts

@@ -0,0 +1,18 @@
+import { effect, signal } from "@pyreon/reactivity"
+
+/**
+ * Track the previous value of a reactive getter.
+ * Returns undefined on first access.
+ */
+export function usePrevious<T>(getter: () => T): () => T | undefined {
+  const prev = signal<T | undefined>(undefined)
+  let current: T | undefined
+
+  effect(() => {
+    const next = getter()
+    prev.set(current)
+    current = next
+  })
+
+  return prev
+}

package/src/useReducedMotion.ts

@@ -0,0 +1,8 @@
+import { useMediaQuery } from "./useMediaQuery"
+
+/**
+ * Returns true when the user prefers reduced motion.
+ */
+export function useReducedMotion(): () => boolean {
+  return useMediaQuery("(prefers-reduced-motion: reduce)")
+}

package/src/useRootSize.ts

@@ -0,0 +1,28 @@
+import { useTheme } from "@pyreon/styler"
+
+type RootSizeResult = {
+  rootSize: number
+  pxToRem: (px: number) => string
+  remToPx: (rem: number) => number
+}
+
+export type UseRootSize = () => RootSizeResult
+
+/**
+ * Returns `rootSize` from the theme context along with
+ * `pxToRem` and `remToPx` conversion utilities.
+ *
+ * Defaults to `16` when no rootSize is set in the theme.
+ */
+export const useRootSize: UseRootSize = () => {
+  const theme = useTheme<{ rootSize?: number | undefined }>()
+  const rootSize = theme?.rootSize ?? 16
+
+  return {
+    rootSize,
+    pxToRem: (px: number) => `${px / rootSize}rem`,
+    remToPx: (rem: number) => rem * rootSize,
+  }
+}
+
+export default useRootSize