@pyreon/hooks 0.11.1 → 0.11.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/hooks",
-  "version": "0.11.1",
+  "version": "0.11.3",
   "repository": {
     "type": "git",
     "url": "https://github.com/pyreon/pyreon",
@@ -24,7 +24,8 @@
     "!lib/**/*.map",
     "!lib/analysis",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "src"
   ],
   "engines": {
     "node": ">= 22"
@@ -43,13 +44,13 @@
     "typecheck": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@pyreon/core": "^0.11.1",
-    "@pyreon/reactivity": "^0.11.1",
-    "@pyreon/styler": "^0.11.1",
-    "@pyreon/ui-core": "^0.11.1"
+    "@pyreon/core": "^0.11.3",
+    "@pyreon/reactivity": "^0.11.3",
+    "@pyreon/styler": "^0.11.3",
+    "@pyreon/ui-core": "^0.11.3"
   },
   "devDependencies": {
     "@vitus-labs/tools-rolldown": "^1.15.3",
-    "@pyreon/typescript": "^0.11.1"
+    "@pyreon/typescript": "^0.11.3"
   }
 }

package/src/__tests__/useBreakpoint.test.ts

@@ -0,0 +1,148 @@
+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 { useBreakpoint } from "../useBreakpoint"
+
+describe("useBreakpoint", () => {
+  const originalInnerWidth = window.innerWidth
+  let rafCallback: FrameRequestCallback | undefined
+
+  beforeEach(() => {
+    mountCallbacks = []
+    unmountCallbacks = []
+    rafCallback = undefined
+
+    vi.spyOn(window, "requestAnimationFrame").mockImplementation((cb) => {
+      rafCallback = cb
+      return 1
+    })
+    vi.spyOn(window, "cancelAnimationFrame").mockImplementation(() => {
+      /* no-op */
+    })
+  })
+
+  afterEach(() => {
+    Object.defineProperty(window, "innerWidth", { writable: true, value: originalInnerWidth })
+    vi.restoreAllMocks()
+  })
+
+  it("returns the active breakpoint based on window width", () => {
+    Object.defineProperty(window, "innerWidth", { writable: true, value: 800 })
+    const bp = useBreakpoint()
+    expect(bp()).toBe("md") // 768 <= 800 < 992
+  })
+
+  it("uses default breakpoints", () => {
+    Object.defineProperty(window, "innerWidth", { writable: true, value: 400 })
+    const bp = useBreakpoint()
+    expect(bp()).toBe("xs") // 0 <= 400 < 576
+
+    Object.defineProperty(window, "innerWidth", { writable: true, value: 600 })
+    const bp2 = useBreakpoint()
+    expect(bp2()).toBe("sm") // 576 <= 600 < 768
+  })
+
+  it("supports custom breakpoints", () => {
+    Object.defineProperty(window, "innerWidth", { writable: true, value: 500 })
+    const bp = useBreakpoint({ mobile: 0, tablet: 600, desktop: 1024 })
+    expect(bp()).toBe("mobile")
+  })
+
+  it("returns largest matching breakpoint", () => {
+    Object.defineProperty(window, "innerWidth", { writable: true, value: 1200 })
+    const bp = useBreakpoint()
+    expect(bp()).toBe("xl")
+  })
+
+  it("returns first breakpoint for very small widths", () => {
+    Object.defineProperty(window, "innerWidth", { writable: true, value: 0 })
+    const bp = useBreakpoint()
+    expect(bp()).toBe("xs")
+  })
+
+  it("updates breakpoint on resize", () => {
+    Object.defineProperty(window, "innerWidth", { writable: true, value: 800 })
+    const bp = useBreakpoint()
+    mountCallbacks.forEach((cb) => {
+      cb()
+    })
+    expect(bp()).toBe("md")
+
+    // Simulate resize
+    Object.defineProperty(window, "innerWidth", { writable: true, value: 1200 })
+    window.dispatchEvent(new Event("resize"))
+
+    // Execute rAF callback
+    rafCallback?.(0)
+    expect(bp()).toBe("xl")
+  })
+
+  it("debounces resize with requestAnimationFrame", () => {
+    Object.defineProperty(window, "innerWidth", { writable: true, value: 800 })
+    const bp = useBreakpoint()
+    mountCallbacks.forEach((cb) => {
+      cb()
+    })
+
+    Object.defineProperty(window, "innerWidth", { writable: true, value: 1200 })
+    window.dispatchEvent(new Event("resize"))
+
+    // Before rAF fires, value should still be old
+    expect(bp()).toBe("md")
+
+    rafCallback?.(0)
+    expect(bp()).toBe("xl")
+  })
+
+  it("cancels pending rAF on new resize", () => {
+    Object.defineProperty(window, "innerWidth", { writable: true, value: 800 })
+    useBreakpoint()
+    mountCallbacks.forEach((cb) => {
+      cb()
+    })
+
+    window.dispatchEvent(new Event("resize"))
+    window.dispatchEvent(new Event("resize"))
+
+    expect(window.cancelAnimationFrame).toHaveBeenCalled()
+  })
+
+  it("cleans up on unmount", () => {
+    const removeSpy = vi.spyOn(window, "removeEventListener")
+    useBreakpoint()
+    mountCallbacks.forEach((cb) => {
+      cb()
+    })
+    unmountCallbacks.forEach((cb) => {
+      cb()
+    })
+
+    expect(removeSpy).toHaveBeenCalledWith("resize", expect.any(Function))
+  })
+
+  it("does not update when breakpoint has not changed", () => {
+    Object.defineProperty(window, "innerWidth", { writable: true, value: 800 })
+    const bp = useBreakpoint()
+    mountCallbacks.forEach((cb) => {
+      cb()
+    })
+
+    // Resize but stay within same breakpoint
+    Object.defineProperty(window, "innerWidth", { writable: true, value: 850 })
+    window.dispatchEvent(new Event("resize"))
+    rafCallback?.(0)
+
+    expect(bp()).toBe("md") // Still md (768-991)
+  })
+})

package/src/__tests__/useClickOutside.test.ts

@@ -0,0 +1,144 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+
+// Capture registered callbacks so we can invoke lifecycle manually
+let mountCallbacks: Array<() => void> = []
+let unmountCallbacks: Array<() => void> = []
+
+vi.mock("@pyreon/core", () => ({
+  onMount: (fn: () => unknown) => {
+    mountCallbacks.push(fn as () => void)
+  },
+  onUnmount: (fn: () => void) => {
+    unmountCallbacks.push(fn)
+  },
+}))
+
+import { useClickOutside } from "../useClickOutside"
+
+describe("useClickOutside", () => {
+  let container: HTMLDivElement
+
+  beforeEach(() => {
+    mountCallbacks = []
+    unmountCallbacks = []
+    container = document.createElement("div")
+    document.body.appendChild(container)
+  })
+
+  afterEach(() => {
+    document.body.removeChild(container)
+  })
+
+  it("calls handler when clicking outside the element", () => {
+    const handler = vi.fn()
+    useClickOutside(() => container, handler)
+
+    // Simulate mount
+    mountCallbacks.forEach((cb) => {
+      cb()
+    })
+
+    const outside = document.createElement("div")
+    document.body.appendChild(outside)
+
+    const event = new MouseEvent("mousedown", { bubbles: true })
+    Object.defineProperty(event, "target", { value: outside })
+    document.dispatchEvent(event)
+
+    expect(handler).toHaveBeenCalledTimes(1)
+    document.body.removeChild(outside)
+  })
+
+  it("does not call handler when clicking inside the element", () => {
+    const handler = vi.fn()
+    const child = document.createElement("span")
+    container.appendChild(child)
+
+    useClickOutside(() => container, handler)
+    mountCallbacks.forEach((cb) => {
+      cb()
+    })
+
+    const event = new MouseEvent("mousedown", { bubbles: true })
+    Object.defineProperty(event, "target", { value: child })
+    document.dispatchEvent(event)
+
+    expect(handler).not.toHaveBeenCalled()
+  })
+
+  it("does not call handler when clicking the element itself", () => {
+    const handler = vi.fn()
+    useClickOutside(() => container, handler)
+    mountCallbacks.forEach((cb) => {
+      cb()
+    })
+
+    const event = new MouseEvent("mousedown", { bubbles: true })
+    Object.defineProperty(event, "target", { value: container })
+    document.dispatchEvent(event)
+
+    expect(handler).not.toHaveBeenCalled()
+  })
+
+  it("does not call handler when element is null", () => {
+    const handler = vi.fn()
+    useClickOutside(() => null, handler)
+    mountCallbacks.forEach((cb) => {
+      cb()
+    })
+
+    const event = new MouseEvent("mousedown", { bubbles: true })
+    Object.defineProperty(event, "target", { value: document.body })
+    document.dispatchEvent(event)
+
+    expect(handler).not.toHaveBeenCalled()
+  })
+
+  it("handles touchstart events", () => {
+    const handler = vi.fn()
+    useClickOutside(() => container, handler)
+    mountCallbacks.forEach((cb) => {
+      cb()
+    })
+
+    const outside = document.createElement("div")
+    document.body.appendChild(outside)
+
+    const event = new Event("touchstart", { bubbles: true })
+    Object.defineProperty(event, "target", { value: outside })
+    document.dispatchEvent(event)
+
+    expect(handler).toHaveBeenCalledTimes(1)
+    document.body.removeChild(outside)
+  })
+
+  it("removes listeners on unmount", () => {
+    const handler = vi.fn()
+    useClickOutside(() => container, handler)
+    mountCallbacks.forEach((cb) => {
+      cb()
+    })
+
+    const removeSpy = vi.spyOn(document, "removeEventListener")
+    unmountCallbacks.forEach((cb) => {
+      cb()
+    })
+
+    expect(removeSpy).toHaveBeenCalledWith("mousedown", expect.any(Function), true)
+    expect(removeSpy).toHaveBeenCalledWith("touchstart", expect.any(Function), true)
+    removeSpy.mockRestore()
+  })
+
+  it("adds listeners with capture phase", () => {
+    const handler = vi.fn()
+    const addSpy = vi.spyOn(document, "addEventListener")
+    useClickOutside(() => container, handler)
+    mountCallbacks.forEach((cb) => {
+      cb()
+    })
+
+    expect(addSpy).toHaveBeenCalledWith("mousedown", expect.any(Function), true)
+    expect(addSpy).toHaveBeenCalledWith("touchstart", expect.any(Function), true)
+    addSpy.mockRestore()
+  })
+})

package/src/__tests__/useColorScheme.test.ts

@@ -0,0 +1,101 @@
+import { 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 { useColorScheme } from "../useColorScheme"
+
+describe("useColorScheme", () => {
+  let changeListeners: Map<string, (e: MediaQueryListEvent) => void>
+
+  beforeEach(() => {
+    mountCallbacks = []
+    unmountCallbacks = []
+    changeListeners = new Map()
+
+    Object.defineProperty(window, "matchMedia", {
+      writable: true,
+      value: vi.fn((query: string) => ({
+        matches: false,
+        media: query,
+        addEventListener: vi.fn((event: string, cb: (e: MediaQueryListEvent) => void) => {
+          if (event === "change") changeListeners.set(query, cb)
+        }),
+        removeEventListener: vi.fn(),
+      })),
+    })
+  })
+
+  it("returns light by default", () => {
+    const scheme = useColorScheme()
+    mountCallbacks.forEach((cb) => {
+      cb()
+    })
+    expect(scheme()).toBe("light")
+  })
+
+  it("returns dark when prefers-color-scheme is dark", () => {
+    Object.defineProperty(window, "matchMedia", {
+      writable: true,
+      value: vi.fn((query: string) => ({
+        matches: true,
+        media: query,
+        addEventListener: vi.fn((event: string, cb: (e: MediaQueryListEvent) => void) => {
+          if (event === "change") changeListeners.set(query, cb)
+        }),
+        removeEventListener: vi.fn(),
+      })),
+    })
+
+    const scheme = useColorScheme()
+    mountCallbacks.forEach((cb) => {
+      cb()
+    })
+    expect(scheme()).toBe("dark")
+  })
+
+  it("updates when color scheme changes from light to dark", () => {
+    const scheme = useColorScheme()
+    mountCallbacks.forEach((cb) => {
+      cb()
+    })
+    expect(scheme()).toBe("light")
+
+    const listener = changeListeners.get("(prefers-color-scheme: dark)")
+    listener?.({ matches: true } as MediaQueryListEvent)
+    expect(scheme()).toBe("dark")
+  })
+
+  it("updates when color scheme changes from dark to light", () => {
+    Object.defineProperty(window, "matchMedia", {
+      writable: true,
+      value: vi.fn((query: string) => ({
+        matches: true,
+        media: query,
+        addEventListener: vi.fn((event: string, cb: (e: MediaQueryListEvent) => void) => {
+          if (event === "change") changeListeners.set(query, cb)
+        }),
+        removeEventListener: vi.fn(),
+      })),
+    })
+
+    const scheme = useColorScheme()
+    mountCallbacks.forEach((cb) => {
+      cb()
+    })
+    expect(scheme()).toBe("dark")
+
+    const listener = changeListeners.get("(prefers-color-scheme: dark)")
+    listener?.({ matches: false } as MediaQueryListEvent)
+    expect(scheme()).toBe("light")
+  })
+})

package/src/__tests__/useControllableState.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it, vi } from "vitest"
+import { useControllableState } from "../useControllableState"
+
+describe("useControllableState", () => {
+  it("uses defaultValue when uncontrolled", () => {
+    const [value] = useControllableState({ defaultValue: "hello" })
+    expect(value()).toBe("hello")
+  })
+
+  it("updates internal state when uncontrolled", () => {
+    const [value, setValue] = useControllableState({ defaultValue: 0 })
+    setValue(5)
+    expect(value()).toBe(5)
+  })
+
+  it("uses value when controlled", () => {
+    const [value] = useControllableState({ value: "controlled", defaultValue: "default" })
+    expect(value()).toBe("controlled")
+  })
+
+  it("does not update internal state when controlled", () => {
+    const onChange = vi.fn()
+    const [value, setValue] = useControllableState({
+      value: "controlled",
+      defaultValue: "default",
+      onChange,
+    })
+    setValue("new")
+    expect(value()).toBe("controlled")
+    expect(onChange).toHaveBeenCalledWith("new")
+  })
+
+  it("calls onChange in uncontrolled mode", () => {
+    const onChange = vi.fn()
+    const [, setValue] = useControllableState({ defaultValue: 0, onChange })
+    setValue(10)
+    expect(onChange).toHaveBeenCalledWith(10)
+  })
+
+  it("supports updater function", () => {
+    const [value, setValue] = useControllableState({ defaultValue: 1 })
+    setValue((prev: number) => prev + 1)
+    expect(value()).toBe(2)
+  })
+})

package/src/__tests__/useDebouncedCallback.test.ts

@@ -0,0 +1,80 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+import { useDebouncedCallback } from "../useDebouncedCallback"
+
+// Mock onUnmount since it requires component lifecycle context
+vi.mock("@pyreon/core", () => ({
+  onMount: (fn: () => void) => fn(),
+  onUnmount: (_fn: () => void) => {
+    /* no-op */
+  },
+}))
+
+describe("useDebouncedCallback", () => {
+  beforeEach(() => vi.useFakeTimers())
+  afterEach(() => vi.useRealTimers())
+
+  it("debounces the callback", () => {
+    const fn = vi.fn()
+    const debounced = useDebouncedCallback(fn, 100)
+
+    debounced("a")
+    debounced("b")
+    debounced("c")
+
+    expect(fn).not.toHaveBeenCalled()
+    vi.advanceTimersByTime(100)
+    expect(fn).toHaveBeenCalledTimes(1)
+    expect(fn).toHaveBeenCalledWith("c")
+  })
+
+  it("cancel prevents the callback", () => {
+    const fn = vi.fn()
+    const debounced = useDebouncedCallback(fn, 100)
+
+    debounced("a")
+    debounced.cancel()
+    vi.advanceTimersByTime(200)
+
+    expect(fn).not.toHaveBeenCalled()
+  })
+
+  it("flush invokes immediately", () => {
+    const fn = vi.fn()
+    const debounced = useDebouncedCallback(fn, 100)
+
+    debounced("x")
+    debounced.flush()
+
+    expect(fn).toHaveBeenCalledWith("x")
+  })
+
+  it("flush is a no-op when no pending timer", () => {
+    const fn = vi.fn()
+    const debounced = useDebouncedCallback(fn, 100)
+
+    debounced.flush()
+    expect(fn).not.toHaveBeenCalled()
+  })
+
+  it("flush is a no-op after timer already fired", () => {
+    const fn = vi.fn()
+    const debounced = useDebouncedCallback(fn, 100)
+
+    debounced("a")
+    vi.advanceTimersByTime(100)
+    expect(fn).toHaveBeenCalledTimes(1)
+
+    debounced.flush()
+    expect(fn).toHaveBeenCalledTimes(1)
+  })
+
+  it("flush is a no-op after cancel", () => {
+    const fn = vi.fn()
+    const debounced = useDebouncedCallback(fn, 100)
+
+    debounced("a")
+    debounced.cancel()
+    debounced.flush()
+    expect(fn).not.toHaveBeenCalled()
+  })
+})

package/src/__tests__/useDebouncedValue.test.ts

@@ -0,0 +1,112 @@
+import { signal } from "@pyreon/reactivity"
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+import { useDebouncedValue } from "../useDebouncedValue"
+
+// Mock onUnmount since it requires component lifecycle context
+vi.mock("@pyreon/core", () => ({
+  onMount: (fn: () => void) => fn(),
+  onUnmount: (_fn: () => void) => {
+    /* no-op */
+  },
+}))
+
+describe("useDebouncedValue", () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it("returns the initial value immediately", () => {
+    const source = signal(42)
+    const debounced = useDebouncedValue(source, 300)
+    expect(debounced()).toBe(42)
+  })
+
+  it("does not update immediately when source changes", () => {
+    const source = signal("hello")
+    const debounced = useDebouncedValue(source, 300)
+    expect(debounced()).toBe("hello")
+
+    source.set("world")
+    expect(debounced()).toBe("hello")
+  })
+
+  it("updates after the delay elapses", () => {
+    const source = signal("hello")
+    const debounced = useDebouncedValue(source, 300)
+
+    source.set("world")
+    expect(debounced()).toBe("hello")
+
+    vi.advanceTimersByTime(300)
+    expect(debounced()).toBe("world")
+  })
+
+  it("resets the timer on rapid changes", () => {
+    const source = signal(1)
+    const debounced = useDebouncedValue(source, 300)
+
+    source.set(2)
+    vi.advanceTimersByTime(100)
+    expect(debounced()).toBe(1)
+
+    source.set(3)
+    vi.advanceTimersByTime(100)
+    expect(debounced()).toBe(1)
+
+    source.set(4)
+    vi.advanceTimersByTime(300)
+    expect(debounced()).toBe(4)
+  })
+
+  it("only applies the last value after debounce", () => {
+    const source = signal(0)
+    const debounced = useDebouncedValue(source, 200)
+
+    source.set(1)
+    source.set(2)
+    source.set(3)
+    source.set(4)
+    source.set(5)
+
+    vi.advanceTimersByTime(200)
+    expect(debounced()).toBe(5)
+  })
+
+  it("handles multiple debounce cycles", () => {
+    const source = signal("a")
+    const debounced = useDebouncedValue(source, 100)
+
+    source.set("b")
+    vi.advanceTimersByTime(100)
+    expect(debounced()).toBe("b")
+
+    source.set("c")
+    vi.advanceTimersByTime(100)
+    expect(debounced()).toBe("c")
+  })
+
+  it("works with zero delay", () => {
+    const source = signal(1)
+    const debounced = useDebouncedValue(source, 0)
+
+    source.set(2)
+    vi.advanceTimersByTime(0)
+    expect(debounced()).toBe(2)
+  })
+
+  it("works with object values", () => {
+    const obj1 = { name: "Alice" }
+    const obj2 = { name: "Bob" }
+    const source = signal(obj1)
+    const debounced = useDebouncedValue(source, 100)
+    expect(debounced()).toBe(obj1)
+
+    source.set(obj2)
+    vi.advanceTimersByTime(100)
+    expect(debounced()).toBe(obj2)
+  })
+})