@pyreon/hooks 0.11.0 → 0.11.2

package/src/useScrollLock.ts

@@ -0,0 +1,37 @@
+import { onUnmount } from "@pyreon/core"
+
+let lockCount = 0
+let savedOverflow = ""
+
+/**
+ * Lock page scroll. Uses reference counting for concurrent locks.
+ * Returns an unlock function.
+ */
+export function useScrollLock(): { lock: () => void; unlock: () => void } {
+  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 }
+}

package/src/useSpacing.ts

@@ -0,0 +1,26 @@
+import useRootSize from "./useRootSize"
+
+export type UseSpacing = (base?: number | undefined) => (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"
+ * ```
+ */
+export const useSpacing: UseSpacing = (base) => {
+  const { rootSize } = useRootSize()
+  const unit = base ?? rootSize / 2
+
+  return (multiplier: number) => `${unit * multiplier}px`
+}
+
+export default useSpacing

package/src/useThemeValue.ts

@@ -0,0 +1,21 @@
+import { useTheme } from "@pyreon/styler"
+import { get } from "@pyreon/ui-core"
+
+export 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')
+ * ```
+ */
+export const useThemeValue: UseThemeValue = (path) => {
+  const theme = useTheme()
+  if (!theme) return undefined
+  return get(theme, path)
+}
+
+export default useThemeValue

package/src/useThrottledCallback.ts

@@ -0,0 +1,30 @@
+import { onUnmount } from "@pyreon/core"
+import { throttle } from "@pyreon/ui-core"
+
+type ThrottledFn<T extends (...args: any[]) => any> = {
+  (...args: Parameters<T>): void
+  cancel: () => void
+}
+
+export 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.
+ */
+export const useThrottledCallback: UseThrottledCallback = (callback, delay) => {
+  const currentCallback = callback
+
+  const throttled = throttle((...args: any[]) => currentCallback(...args), delay)
+
+  onUnmount(() => throttled.cancel())
+
+  return throttled as ThrottledFn<typeof callback>
+}
+
+export default useThrottledCallback

package/src/useTimeAgo.ts

@@ -0,0 +1,134 @@
+import { onCleanup, signal } from "@pyreon/reactivity"
+
+type TimeUnit = "second" | "minute" | "hour" | "day" | "week" | "month" | "year"
+
+interface TimeInterval {
+  unit: TimeUnit
+  seconds: number
+}
+
+const INTERVALS: TimeInterval[] = [
+  { unit: "year", seconds: 31536000 },
+  { unit: "month", seconds: 2592000 },
+  { unit: "week", seconds: 604800 },
+  { unit: "day", seconds: 86400 },
+  { unit: "hour", seconds: 3600 },
+  { unit: "minute", seconds: 60 },
+  { unit: "second", seconds: 1 },
+]
+
+/**
+ * Determine how often to update based on the age of the timestamp.
+ * Recent times update more frequently.
+ */
+function getRefreshInterval(diffSeconds: number): number {
+  if (diffSeconds < 60) return 1000 // every second for <1min
+  if (diffSeconds < 3600) return 30_000 // every 30s for <1hr
+  if (diffSeconds < 86400) return 300_000 // every 5min for <1day
+  return 3600_000 // every hour for older
+}
+
+export interface UseTimeAgoOptions {
+  /** Custom formatter. Receives the value, unit, and whether it's in the past. */
+  formatter?: (value: number, unit: TimeUnit, isPast: boolean) => string
+  /** Update interval override in ms. If not set, adapts based on age. */
+  interval?: number
+}
+
+/**
+ * Default English formatter using Intl.RelativeTimeFormat.
+ */
+const defaultFormatter = (() => {
+  const rtf =
+    typeof Intl !== "undefined" ? new Intl.RelativeTimeFormat("en", { numeric: "auto" }) : undefined
+
+  return (value: number, unit: TimeUnit, isPast: boolean): string => {
+    if (rtf) return rtf.format(isPast ? -value : value, unit)
+    // Fallback for environments without Intl
+    const label = value === 1 ? unit : `${unit}s`
+    return isPast ? `${value} ${label} ago` : `in ${value} ${label}`
+  }
+})()
+
+/**
+ * Compute the relative time string for a given timestamp.
+ */
+function computeTimeAgo(
+  date: Date | number,
+  formatter: (value: number, unit: TimeUnit, isPast: boolean) => string,
+): string {
+  const now = Date.now()
+  const target = typeof date === "number" ? date : date.getTime()
+  const diff = Math.abs(now - target)
+  const diffSeconds = Math.floor(diff / 1000)
+  const isPast = target < now
+
+  if (diffSeconds < 5) return "just now"
+
+  for (const { unit, seconds } of INTERVALS) {
+    const value = Math.floor(diffSeconds / seconds)
+    if (value >= 1) return formatter(value, unit, isPast)
+  }
+
+  return "just now"
+}
+
+/**
+ * Reactive relative time that auto-updates.
+ * Returns a signal that displays "2 minutes ago", "just now", etc.
+ *
+ * @param date - Date object, timestamp, or reactive getter
+ *
+ * @example
+ * ```tsx
+ * const timeAgo = useTimeAgo(post.createdAt)
+ * <span>{timeAgo}</span>
+ * // Renders: "5 minutes ago" → "6 minutes ago" (auto-updates)
+ *
+ * // With reactive date:
+ * const timeAgo = useTimeAgo(() => selectedPost().createdAt)
+ *
+ * // With custom formatter (e.g. for i18n):
+ * const timeAgo = useTimeAgo(date, {
+ *   formatter: (value, unit, isPast) => t('time.' + unit, { count: value })
+ * })
+ * ```
+ */
+export function useTimeAgo(
+  date: Date | number | (() => Date | number),
+  options?: UseTimeAgoOptions,
+): () => string {
+  const formatter = options?.formatter ?? defaultFormatter
+  const resolveDate = typeof date === "function" ? date : () => date
+
+  const result = signal(computeTimeAgo(resolveDate(), formatter))
+
+  // Disposed flag prevents timer chain from continuing after cleanup.
+  // Without this, the setTimeout callback could fire after the component
+  // unmounts, scheduling yet another timer indefinitely.
+  let timer: ReturnType<typeof setTimeout> | undefined
+  let disposed = false
+
+  function tick() {
+    if (disposed) return
+
+    const d = resolveDate()
+    result.set(computeTimeAgo(d, formatter))
+
+    // Schedule next update with adaptive interval
+    const target = typeof d === "number" ? d : d.getTime()
+    const diffSeconds = Math.floor(Math.abs(Date.now() - target) / 1000)
+    const interval = options?.interval ?? getRefreshInterval(diffSeconds)
+    timer = setTimeout(tick, interval)
+  }
+
+  // Schedule first tick (don't call synchronously — let cleanup register first)
+  timer = setTimeout(tick, 0)
+
+  onCleanup(() => {
+    disposed = true
+    if (timer) clearTimeout(timer)
+  })
+
+  return result
+}

package/src/useTimeout.ts

@@ -0,0 +1,42 @@
+import { onUnmount } from "@pyreon/core"
+
+export 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).
+ */
+export const useTimeout: UseTimeout = (callback, delay) => {
+  const currentCallback = callback
+  let timer: ReturnType<typeof setTimeout> | null = null
+
+  const clear = () => {
+    if (timer != null) {
+      clearTimeout(timer)
+      timer = null
+    }
+  }
+
+  const reset = () => {
+    clear()
+    if (delay !== null) {
+      timer = setTimeout(() => {
+        timer = null
+        currentCallback()
+      }, delay)
+    }
+  }
+
+  // Start the timer immediately
+  reset()
+
+  onUnmount(() => clear())
+
+  return { reset, clear }
+}
+
+export default useTimeout

package/src/useToggle.ts

@@ -0,0 +1,22 @@
+import { signal } from "@pyreon/reactivity"
+
+export interface UseToggleResult {
+  value: () => boolean
+  toggle: () => void
+  setTrue: () => void
+  setFalse: () => void
+}
+
+/**
+ * Simple boolean toggle.
+ */
+export function useToggle(initial = false): UseToggleResult {
+  const value = signal(initial)
+
+  return {
+    value,
+    toggle: () => value.update((v) => !v),
+    setTrue: () => value.set(true),
+    setFalse: () => value.set(false),
+  }
+}

package/src/useUpdateEffect.ts

@@ -0,0 +1,24 @@
+import { onUnmount } from "@pyreon/core"
+import { watch } from "@pyreon/reactivity"
+
+export 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)
+ */
+export const useUpdateEffect: UseUpdateEffect = (source, callback) => {
+  const stop = watch(source, callback)
+
+  onUnmount(() => stop())
+}
+
+export default useUpdateEffect

package/src/useWindowResize.ts

@@ -0,0 +1,39 @@
+import { onMount, onUnmount } from "@pyreon/core"
+import { signal } from "@pyreon/reactivity"
+
+export interface WindowSize {
+  width: number
+  height: number
+}
+
+/**
+ * Track window dimensions reactively with throttling.
+ */
+export function useWindowResize(throttleMs = 200): () => WindowSize {
+  const size = signal<WindowSize>({
+    width: typeof window !== "undefined" ? window.innerWidth : 0,
+    height: typeof window !== "undefined" ? window.innerHeight : 0,
+  })
+
+  let timer: ReturnType<typeof setTimeout> | undefined
+
+  function onResize() {
+    if (timer !== undefined) return
+    timer = setTimeout(() => {
+      timer = undefined
+      size.set({ width: window.innerWidth, height: window.innerHeight })
+    }, throttleMs)
+  }
+
+  onMount(() => {
+    window.addEventListener("resize", onResize)
+    return undefined
+  })
+
+  onUnmount(() => {
+    window.removeEventListener("resize", onResize)
+    if (timer !== undefined) clearTimeout(timer)
+  })
+
+  return size
+}