use-scroller 1.1.0 → 1.2.0

package/src/hooks/use-scroll.ts

@@ -1,62 +1,39 @@
-import { useCallback, useRef, useState } from 'react'
-import { scroller } from '../scroller'
+import { useRef, useState } from 'react'
+import { createScroller } from '../scroller'
 import { ScrollOptions } from '../types'
 import { defaultScrollOptions, getElement } from '../utils'
 import { useIsoMorphicEffect } from './use-iso-morphic-effect'
 
+const initialState = {
+  left: 0, // Current scroll position on the X-axis
+  top: 0, // Current scroll position on the Y-axis
+  isScrollable: false, // Determines if the container has content that can be scrolled
+  isScrolledLeft: true, // Determines if the container is at its leftmost position
+  isScrolledRight: false, // Determines if the container is at its rightmost position
+  isScrolledTop: true, // Determines if the container is at its topmost position
+  isScrolledBottom: false, // Determines if the container is at its bottommost position
+  maxScrollLeft: 0, // Maximum possible scroll on the X-axis
+  maxScrollTop: 0, // Maximum possible scroll on the Y-axis
+  scrollPercentageX: 0, // Percentage of horizontal scroll covered
+  scrollPercentageY: 0, // Percentage of vertical scroll covered
+}
+
 export function useScroll<T extends HTMLElement>(props?: Partial<ScrollOptions>) {
   const ref = useRef<T>(null)
-  const [state, setState] = useState(() => ({
-    left: 0,
-    top: 0,
-    isScrollable: false,
-    isScrolledLeft: false,
-    isScrolledRight: false,
-    isScrolledTop: false,
-    isScrolledBottom: false,
-  }))
   const scrollOpt = { ...defaultScrollOptions, ...props }
-
-  const scroll = useCallback((from: number, to: number) => {
-    const container = getElement(ref)
-    const scrollContainer = scroller({ container, options: scrollOpt })
-    scrollContainer.scrollTo(from, to)
-  }, [])
-
-  const scrollCenter = useCallback(() => {
-    const container = getElement(ref)
-    const scrollContainer = scroller({ container, options: scrollOpt })
-    scrollContainer.scrollToCenter()
-  }, [])
-
-  const scrollTop = useCallback((offset?: number) => {
-    const container = getElement(ref)
-    const scrollContainer = scroller({ container, options: scrollOpt })
-    scrollContainer.scrollToTop(offset)
-  }, [])
-
-  const scrollBottom = useCallback((offset?: number) => {
-    const container = getElement(ref)
-    const scrollContainer = scroller({ container, options: scrollOpt })
-    scrollContainer.scrollToBottom(offset)
-  }, [])
-
-  const scrollRight = useCallback((offset?: number) => {
-    const container = getElement(ref)
-    const scrollContainer = scroller({ container, options: scrollOpt })
-    scrollContainer.scrollToRight(offset)
-  }, [])
-
-  const scrollLeft = useCallback((offset?: number) => {
-    const container = getElement(ref)
-    const scrollContainer = scroller({ container, options: scrollOpt })
-    scrollContainer.scrollToLeft(offset)
-  }, [])
+  const scrollerRef = useRef<ReturnType<typeof createScroller> | null>(null)
+  const [state, setState] = useState(() => initialState)
 
   useIsoMorphicEffect(() => {
     const scrollContainer = ref.current
     if (!scrollContainer) return
 
+    // Create the scroller instance only once inside the effect
+    if (!scrollerRef.current) {
+      const container = getElement(ref)
+      scrollerRef.current = createScroller(container, scrollOpt)
+    }
+
     const { scrollWidth, clientWidth, clientHeight, scrollHeight } = scrollContainer
     const isScrollable = clientWidth !== scrollWidth || clientHeight !== scrollHeight
     setState((prev) => ({ ...prev, isScrollable }))
@@ -64,14 +41,26 @@ export function useScroll<T extends HTMLElement>(props?: Partial<ScrollOptions>)
     const handleScroll = () => {
       if (scrollContainer) {
         const { scrollLeft, scrollTop } = scrollContainer
+        const isAtLeftBoundary = scrollLeft === 0
+        const isAtRightBoundary = scrollLeft >= scrollWidth - clientWidth
+        const isAtTopBoundary = scrollTop === 0
+        const isAtBottomBoundary = scrollTop >= scrollHeight - clientHeight
         const scrollState = {
           ...state,
-          isScrolledLeft: scrollLeft === 0,
-          isScrolledRight: scrollLeft >= scrollWidth - clientWidth,
-          isScrolledTop: scrollTop === 0,
-          isScrolledBottom: scrollTop >= scrollHeight - clientHeight,
+          isScrolledLeft: isAtLeftBoundary,
+          isScrolledRight: isAtRightBoundary,
+          isScrolledTop: isAtTopBoundary,
+          isScrolledBottom: isAtBottomBoundary,
           left: scrollLeft,
           top: scrollTop,
+          maxScrollLeft: scrollWidth - clientWidth,
+          maxScrollTop: scrollHeight - clientHeight,
+          scrollPercentageX: isAtLeftBoundary
+            ? 0
+            : (scrollLeft / (scrollWidth - clientWidth)) * 100,
+          scrollPercentageY: isAtTopBoundary
+            ? 0
+            : (scrollTop / (scrollHeight - clientHeight)) * 100,
         }
         setState(scrollState)
       }
@@ -80,16 +69,16 @@ export function useScroll<T extends HTMLElement>(props?: Partial<ScrollOptions>)
     handleScroll()
     scrollContainer?.addEventListener('scroll', handleScroll)
     return () => scrollContainer?.removeEventListener('scroll', handleScroll)
-  }, [])
+  }, [state])
 
   return {
     ref,
     state,
-    scrollLeft,
-    scrollRight,
-    scrollBottom,
-    scrollTop,
-    scrollCenter,
-    scroll,
+    scrollLeft: scrollerRef.current?.scrollToLeft,
+    scrollRight: scrollerRef.current?.scrollToRight,
+    scrollBottom: scrollerRef.current?.scrollToBottom,
+    scrollTop: scrollerRef.current?.scrollToTop,
+    scrollCenter: scrollerRef.current?.scrollToCenter,
+    scrollTo: scrollerRef.current?.scrollTo,
   }
 }

package/src/hooks/use-window-scroll.ts

@@ -1,6 +1,6 @@
 import { useCallback, useState } from 'react'
-import { scroller } from '../scroller'
-import { ScrollerProps, ScrollOptions } from '../types'
+import { createScroller } from '../scroller'
+import { ScrollOptions } from '../types'
 import { useIsoMorphicEffect } from './use-iso-morphic-effect'
 import { defaultScrollOptions, resolveScrollValues } from '../utils'
 
@@ -12,49 +12,62 @@ export function useWindowScroll(props?: Partial<Omit<ScrollOptions, 'direction'>
     isScrolledBottom: false,
   }))
 
-  const scrollArgs: ScrollerProps = {
-    container: window,
-    options: { ...defaultScrollOptions, ...props },
-  }
-  const scroll = useCallback((from: number, to: number) => {
-    const scrollContainer = scroller(scrollArgs)
-    scrollContainer.scrollTo(from, to)
-  }, [])
-
-  const scrollToTarget = useCallback((currentTarget: HTMLElement) => {
-    const scrollContainer = scroller(scrollArgs)
-    scrollContainer.scrollToTarget(currentTarget)
-  }, [])
-
-  const scrollTop = useCallback((offset?: number | undefined) => {
-    const scrollContainer = scroller(scrollArgs)
-    scrollContainer.scrollToTop(offset)
-  }, [])
-
-  const scrollBottom = useCallback((offset?: number | undefined) => {
-    const scrollContainer = scroller(scrollArgs)
-    scrollContainer.scrollToBottom(offset)
-  }, [])
+  const container = window
+  const scrollOptions = { ...defaultScrollOptions, ...props }
 
-  useIsoMorphicEffect(() => {
-    const handleScroll = () => {
-      if (window) {
-        const { scrollLeft, scrollTop, scrollHeight, clientHeight } = resolveScrollValues(window)
-        const scrollState = {
-          ...state,
-          isScrolledTop: scrollTop === 0,
-          isScrolledBottom: scrollTop >= scrollHeight - clientHeight,
-          left: scrollLeft,
-          top: scrollTop,
-        }
-        setState(scrollState)
-      }
+  const scrollContainer = createScroller(container, scrollOptions)
+
+  const handleScroll = useCallback(() => {
+    const { scrollLeft, scrollTop, clientHeight, scrollHeight } = resolveScrollValues(container)
+
+    const isAtTopBoundary = scrollTop === 0
+    const isAtBottomBoundary = scrollTop >= scrollHeight - clientHeight
+
+    const scrollState = {
+      left: scrollLeft,
+      top: scrollTop,
+      isScrolledTop: isAtTopBoundary,
+      isScrolledBottom: isAtBottomBoundary,
     }
 
+    setState(scrollState)
+  }, [container])
+
+  useIsoMorphicEffect(() => {
     handleScroll()
-    window?.addEventListener('scroll', handleScroll)
-    return () => window?.removeEventListener('scroll', handleScroll)
-  }, [])
+    container.addEventListener('scroll', handleScroll)
+    return () => {
+      container.removeEventListener('scroll', handleScroll)
+    }
+  }, [handleScroll])
+
+  const scrollTo = useCallback(
+    (position: number) => {
+      scrollContainer.scrollTo(position)
+    },
+    [scrollContainer]
+  )
+
+  const scrollToTarget = useCallback(
+    (currentTarget: HTMLElement) => {
+      scrollContainer.scrollToTarget(currentTarget)
+    },
+    [scrollContainer]
+  )
+
+  const scrollTop = useCallback(
+    (offset?: number | undefined) => {
+      scrollContainer.scrollToTop(offset)
+    },
+    [scrollContainer]
+  )
+
+  const scrollBottom = useCallback(
+    (offset?: number | undefined) => {
+      scrollContainer.scrollToBottom(offset)
+    },
+    [scrollContainer]
+  )
 
-  return { state, scrollTop, scrollBottom, scrollToTarget, scroll }
+  return { state, scrollTop, scrollBottom, scrollToTarget, scrollTo }
 }

package/src/scroller.ts

@@ -1,44 +1,53 @@
-import { ScrollerProps } from './types'
+import { ScrollOptions } from './types'
 import { defaultScrollOptions, getEasing, resolveScrollValues, validateElement } from './utils'
 
-export function scroller({ container, options = defaultScrollOptions }: ScrollerProps) {
+export function createScroller(
+  container: HTMLElement | Window,
+  options: ScrollOptions = defaultScrollOptions
+) {
   validateElement(container)
-
   const { duration, easingOption, direction } = options
   const { scrollLeft, scrollTop, clientWidth, clientHeight, scrollWidth, scrollHeight } =
     resolveScrollValues(container)
 
-  /**
-   * Scroll the Element or Window to the given
-   * position.
-   *
-   * @param {number} from the current scroll position.
-   * @param {number} to the new position to scroll.
-   * @param {string} layout the scroll direction.
-   */
-  function scrollTo(from: number, to: number, layout: 'horizontal' | 'vertical' = direction) {
+  function scroll(from: number, to: number, layout: ScrollOptions['direction'] = direction) {
     let startTime: number | null = null
     let requestId = 0
+    const distance = Math.abs(to - from)
 
-    function loop(currentTime: number) {
-      if (!startTime) startTime = currentTime
-
-      const time = Math.min((currentTime - startTime) / duration, 1)
+    function calculateCurrentPosition(timeFraction: number): number {
       const easingFunc = getEasing(easingOption)
-      const currentPositionInTime = easingFunc(time) * (to - from) + from
+      return easingFunc(timeFraction) * distance + from
+    }
 
+    function updateScrollPosition(currentPosition: number) {
       container.scrollTo({
-        left: layout === 'horizontal' ? currentPositionInTime : undefined,
-        top: layout === 'vertical' ? currentPositionInTime : undefined,
+        left: layout === 'horizontal' ? currentPosition : undefined,
+        top: layout === 'vertical' ? currentPosition : undefined,
       })
+    }
+
+    function animateScroll(currentTime: number) {
+      if (!startTime) startTime = currentTime
+      const elapsedTime = currentTime - startTime
+      const timeFraction = elapsedTime / duration
+      const currentPosition = calculateCurrentPosition(timeFraction)
+
+      updateScrollPosition(currentPosition)
 
-      if (time < 1) {
-        requestId = requestAnimationFrame(loop)
+      if (timeFraction < 1) {
+        requestId = requestAnimationFrame(animateScroll)
       } else {
         cancelAnimationFrame(requestId)
       }
     }
-    requestId = requestAnimationFrame(loop)
+
+    requestId = requestAnimationFrame(animateScroll)
+  }
+
+  function scrollTo(to: number) {
+    const from = direction === 'vertical' ? scrollTop : scrollLeft
+    scroll(from, to)
   }
 
   function scrollToCenter() {
@@ -56,10 +65,10 @@ export function scroller({ container, options = defaultScrollOptions }: Scroller
       from = scrollLeft
       to = scrollXCenterPosition
     }
-    scrollTo(from, to, direction)
+    scroll(from, to, direction)
   }
 
-  function scrollToTarget(target: HTMLElement) {
+  function scrollToTarget(target: HTMLElement, offset = 0) {
     validateElement(target)
     const { offsetTop, offsetLeft } = target
     let from = 0
@@ -67,44 +76,32 @@ export function scroller({ container, options = defaultScrollOptions }: Scroller
 
     if (direction === 'vertical') {
       from = scrollTop
-      to = offsetTop
+      to = offsetTop - offset
     }
 
     if (direction === 'horizontal') {
       from = scrollLeft
-      to = offsetLeft
+      to = offsetLeft - offset
     }
 
-    scrollTo(from, to, direction)
-  }
-
-  const scrollToLeft = (offset?: number) => {
-    const scrollPosition = offset || scrollLeft - clientWidth
-    scrollTo(scrollLeft, scrollPosition, 'horizontal')
-  }
-
-  const scrollToRight = (offset?: number) => {
-    const scrollPosition = offset || scrollLeft + clientWidth
-    scrollTo(scrollLeft, scrollPosition, 'horizontal')
-  }
-
-  const scrollToTop = (offset?: number) => {
-    const scrollPosition = offset || scrollTop - clientHeight
-    scrollTo(scrollTop, scrollPosition, 'vertical')
-  }
-
-  const scrollToBottom = (offset?: number) => {
-    const scrollPosition = offset || scrollTop + clientHeight
-    scrollTo(scrollTop, scrollPosition, 'vertical')
+    scroll(from, to, direction)
   }
 
   return {
-    scrollToLeft,
-    scrollToRight,
-    scrollToTop,
-    scrollToBottom,
-    scrollToTarget,
-    scrollToCenter,
     scrollTo,
+    scrollToCenter,
+    scrollToTarget,
+    scrollToLeft: (offset?: number) => {
+      scroll(scrollLeft, offset || scrollLeft - clientWidth, 'horizontal')
+    },
+    scrollToRight: (offset?: number) => {
+      scroll(scrollLeft, offset || scrollLeft + clientWidth, 'horizontal')
+    },
+    scrollToTop: (offset?: number) => {
+      scroll(scrollTop, offset || scrollTop - clientHeight, 'vertical')
+    },
+    scrollToBottom: (offset?: number) => {
+      scroll(scrollTop, offset || scrollTop + clientHeight, 'vertical')
+    },
   }
 }

package/src/utils.ts

@@ -1,8 +1,10 @@
 import { RefObject } from 'react'
 import { EasingFunction, EasingFunctions, EasingOptions, ScrollOptions } from './types'
 
+// Check if the code is running on the server-side.
 export const isServer = typeof window === 'undefined' || typeof document === 'undefined'
 
+// Default scroll options used if no options are provided.
 export const defaultScrollOptions: ScrollOptions = {
   direction: 'vertical',
   duration: 300,
@@ -10,37 +12,37 @@ export const defaultScrollOptions: ScrollOptions = {
 }
 
 /**
- * Resolves scroll values based on the type of param.
- * @param {HTMLElement | Window} element
+ * Resolves scroll values based on the type of element.
+ * @param {HTMLElement | Window} element - The element to retrieve scroll values from.
+ * @returns {object} - An object containing scroll-related properties.
  */
 export const resolveScrollValues = (element: HTMLElement | Window) => {
-  if (
-    element === document.body ||
-    element === document.documentElement ||
-    element instanceof Window
-  ) {
-    return {
-      scrollLeft: document.body.scrollLeft || document.documentElement.scrollLeft,
-      scrollTop: document.body.scrollTop || document.documentElement.scrollTop,
-      scrollWidth: document.body.scrollWidth || document.documentElement.scrollWidth,
-      clientWidth: document.body.clientWidth || document.documentElement.clientWidth,
-      clientHeight: document.body.clientHeight || document.documentElement.clientHeight,
-      scrollHeight: document.body.scrollHeight || document.documentElement.scrollHeight,
-    }
-  }
+  const isWindow = element instanceof Window
+  const docElement = document.documentElement
+  const docBody = document.body
+
+  const scrollLeftMax = isWindow
+    ? Math.max(docBody.scrollLeft, docElement.scrollLeft)
+    : element.scrollWidth - element.clientWidth
+  const scrollTopMax = isWindow
+    ? Math.max(docBody.scrollTop, docElement.scrollTop)
+    : element.scrollHeight - element.clientHeight
+
   return {
-    scrollLeft: element.scrollLeft,
-    scrollTop: element.scrollTop,
-    scrollWidth: element.scrollWidth,
-    clientWidth: element.clientWidth,
-    clientHeight: element.clientHeight,
-    scrollHeight: element.scrollHeight,
+    scrollLeft: isWindow ? docBody.scrollLeft || docElement.scrollLeft : element.scrollLeft,
+    scrollTop: isWindow ? docBody.scrollTop || docElement.scrollTop : element.scrollTop,
+    scrollWidth: isWindow ? docBody.scrollWidth || docElement.scrollWidth : element.scrollWidth,
+    clientWidth: isWindow ? docBody.clientWidth || docElement.clientWidth : element.clientWidth,
+    clientHeight: isWindow ? docBody.clientHeight || docElement.clientHeight : element.clientHeight,
+    scrollHeight: isWindow ? docBody.scrollHeight || docElement.scrollHeight : element.scrollHeight,
+    scrollLeftMax,
+    scrollTopMax,
   }
 }
 
 /**
- * Validate if element passed to the function is valid.
- * @param {HTMLElement | Window} element
+ * Validate if the element passed to the function is valid.
+ * @param {HTMLElement | Window} element - The element to validate.
  */
 export function validateElement(element?: HTMLElement | Window) {
   if (element === undefined) {
@@ -56,6 +58,11 @@ export function validateElement(element?: HTMLElement | Window) {
   }
 }
 
+/**
+ * Get the DOM element from a React ref object.
+ * @param {RefObject<HTMLElement>} ref - The React ref object.
+ * @returns {HTMLElement} - The DOM element.
+ */
 export const getElement = (ref: RefObject<HTMLElement>) => {
   if (!ref.current) {
     throw new Error(`Could not resolve ref object: ${ref.current}`)
@@ -63,6 +70,7 @@ export const getElement = (ref: RefObject<HTMLElement>) => {
   return ref.current
 }
 
+// Map of easing functions for scroll animations.
 export const easingMap: EasingFunctions = {
   linear(t: number) {
     return t
@@ -78,6 +86,11 @@ export const easingMap: EasingFunctions = {
   },
 }
 
+/**
+ * Get an easing function based on the provided easing option or the default option.
+ * @param {EasingOptions} easing - The easing option.
+ * @returns {EasingFunction} - The easing function.
+ */
 export const getEasing = (easing?: EasingOptions): EasingFunction => {
   const easeFunc = easingMap[easing || defaultScrollOptions.easingOption]
   if (!easeFunc) {