feat: Add support for target elements in usePosition hook

Author: andrewscwei

src/hooks/usePosition.ts

@@ -1,5 +1,5 @@
-import { type DependencyList, useLayoutEffect, useRef } from 'react'
-import { Point, Rect } from 'spase'
+import { type DependencyList, type RefObject, useLayoutEffect, useRef } from 'react'
+import { Point } from 'spase'
 
 import { useLatest } from './useLatest.js'
 
@@ -10,23 +10,41 @@ export type ScrollPositionInfo = {
   step: Point
 }
 
+type Target = HTMLElement | null | RefObject<HTMLElement> | RefObject<HTMLElement | null> | RefObject<HTMLElement | undefined> | undefined
+
 /**
- * Hook for tracking the scroll position of the viewport.
+ * Hook for tracking the scroll position of a target element or the viewport.
  *
+ * @param target Optional target element or ref to track. If not provided, the
+ *               viewport is tracked instead.
  * @param onChange Handler invoked when the scroll position changes.
  * @param deps Optional dependency list to control when the hook should re-run.
  */
+export function usePosition(
+  target: Target,
+  onChange: (newInfo: ScrollPositionInfo, oldInfo: ScrollPositionInfo | undefined) => void,
+  deps?: DependencyList,
+): void
 export function usePosition(
   onChange: (newInfo: ScrollPositionInfo, oldInfo: ScrollPositionInfo | undefined) => void,
-  deps: DependencyList = [],
-) {
+  deps?: DependencyList,
+): void
+export function usePosition(...args:
+  | [(newInfo: ScrollPositionInfo, oldInfo: ScrollPositionInfo | undefined) => void, DependencyList?]
+  | [Target, (newInfo: ScrollPositionInfo, oldInfo: ScrollPositionInfo | undefined) => void, DependencyList?]) {
+  const target = typeof args[0] === 'function' ? undefined : args[0]
+  const onChange = typeof args[0] === 'function' ? args[0] : args[1] as (newInfo: ScrollPositionInfo, oldInfo: ScrollPositionInfo | undefined) => void
+  const deps = typeof args[0] === 'function' ? (args[1] as DependencyList | undefined) ?? [] : (args[2] as DependencyList | undefined) ?? []
+
   const changeHandlerRef = useLatest(onChange)
   const prevInfoRef = useRef<ScrollPositionInfo>(undefined)
   const isTickingRef = useRef(false)
 
   useLayoutEffect(() => {
+    const el = _resolveTarget(target)
+
     const handler = () => {
-      const newInfo = _getScrollPositionInfo()
+      const newInfo = el ? _getElementScrollPositionInfo(el) : _getViewportScrollPositionInfo()
       if (!newInfo) return
 
       changeHandlerRef.current(newInfo, prevInfoRef.current)
@@ -45,32 +63,53 @@ export function usePosition(
       })
     }
 
-    window.addEventListener('scroll', tick, { passive: true })
+    const scrollTarget = el ?? window
+
+    scrollTarget.addEventListener('scroll', tick, { passive: true })
     window.addEventListener('resize', tick)
     window.addEventListener('orientationchange', tick)
 
     tick()
 
     return () => {
-      window.removeEventListener('scroll', tick)
+      scrollTarget.removeEventListener('scroll', tick)
       window.removeEventListener('resize', tick)
       window.removeEventListener('orientationchange', tick)
     }
   }, [...deps])
 }
 
-function _getScrollPositionInfo(): ScrollPositionInfo | undefined {
-  const refRect = Rect.fromViewport()
-  const refRectMin = Rect.clone(refRect, { x: 0, y: 0 })
-  const refRectFull = Rect.from(window, { overflow: true })
+function _resolveTarget(target: Target): HTMLElement | undefined {
+  if (target == null) return undefined
+  if (target instanceof HTMLElement) return target
+
+  return target.current ?? undefined
+}
+
+function _getViewportScrollPositionInfo(): ScrollPositionInfo | undefined {
+  const scrollLeft = window.scrollX
+  const scrollTop = window.scrollY
+  const maxScrollLeft = document.documentElement.scrollWidth - window.innerWidth
+  const maxScrollTop = document.documentElement.scrollHeight - window.innerHeight
+
+  return {
+    maxPos: Point.make(maxScrollLeft, maxScrollTop),
+    minPos: Point.make(0, 0),
+    pos: Point.make(scrollLeft, scrollTop),
+    step: Point.make(maxScrollLeft > 0 ? scrollLeft / maxScrollLeft : 0, maxScrollTop > 0 ? scrollTop / maxScrollTop : 0),
+  }
+}
 
-  const refRectMax = Rect.clone(refRectMin, { x: refRectFull.width - refRect.width, y: refRectFull.height - refRect.height })
-  const step = Point.make(refRect.left / refRectMax.left, refRect.top / refRectMax.top)
+function _getElementScrollPositionInfo(element: HTMLElement): ScrollPositionInfo | undefined {
+  const scrollLeft = element.scrollLeft
+  const scrollTop = element.scrollTop
+  const maxScrollLeft = element.scrollWidth - element.clientWidth
+  const maxScrollTop = element.scrollHeight - element.clientHeight
 
   return {
-    maxPos: Point.make(refRectMax.left, refRectMax.top),
-    minPos: Point.make(refRectMin.left, refRectMin.top),
-    pos: Point.make(refRect.left, refRect.top),
-    step,
+    maxPos: Point.make(maxScrollLeft, maxScrollTop),
+    minPos: Point.make(0, 0),
+    pos: Point.make(scrollLeft, scrollTop),
+    step: Point.make(maxScrollLeft > 0 ? scrollLeft / maxScrollLeft : 0, maxScrollTop > 0 ? scrollTop / maxScrollTop : 0),
   }
 }