feat: add useStickyEvent hook

Author: Elessar1802

src/Shared/Hooks/index.ts

@@ -18,3 +18,4 @@ export * from './UsePrompt'
 export * from './useGetResourceKindsOptions'
 export * from './UseDownload'
 export * from './useForm'
+export * from './useStickyEvent'

src/Shared/Hooks/useStickyEvent/constants.ts

@@ -0,0 +1,3 @@
+export const FALLBACK_SENTINEL_HEIGHT = '1px'
+export const OBSERVER_THRESHOLD = 1
+export const OBSERVER_ROOT_MARGIN = '0px'

src/Shared/Hooks/useStickyEvent/index.ts

@@ -0,0 +1 @@
+export { default as useStickyEvent } from './useStickyEvent'

src/Shared/Hooks/useStickyEvent/styles.scss

@@ -0,0 +1,9 @@
+.sticky-container__sentinel {
+    position: absolute;
+    bottom: 100%;
+    left: 0;
+    right: 0;
+    flex-shrink: 0;
+    visibility: hidden;
+    z-index: -1;
+}

src/Shared/Hooks/useStickyEvent/types.ts

@@ -0,0 +1,33 @@
+import { Dispatch, SetStateAction, MutableRefObject } from 'react'
+
+export type UseStickyEventProps<T extends HTMLElement = HTMLDivElement> = {
+    /**
+     * Callback function that is called when the sticky element is 'stuck' or 'unstuck'
+     */
+    callback: (isStuck: boolean) => void | Dispatch<SetStateAction<boolean>>
+    /**
+     * Unique identifier used to create the id of the sentinel element
+     *
+     * A sentinel element is used to determine when the sticky element is 'stuck'
+     * It is dynamically created and appended to the DOM
+     */
+    identifier: string
+    /**
+     * Indicates whether the sticky element is conditionally rendered.
+     * - Set to true if the sticky element is mounted.
+     * - Set to false if the sticky element is not mounted.
+     * - If the sticky element is always rendered, this flag can be ignored.
+     */
+    isStickyElementMounted?: boolean
+} & (
+    | {
+          /**
+           * Reference to the scroll container element that contains the sticky element
+           *
+           * Either the reference can be passed or its class name
+           */
+          containerRef: MutableRefObject<T>
+          containerClassName?: never
+      }
+    | { containerClassName: string; containerRef?: never }
+)

src/Shared/Hooks/useStickyEvent/useStickyEvent.ts

@@ -0,0 +1,96 @@
+import { useEffect, useRef } from 'react'
+import { isNullOrUndefined } from '@Shared/Helpers'
+import { noop } from '@Common/Helper'
+import { UseStickyEventProps } from './types'
+import { FALLBACK_SENTINEL_HEIGHT, OBSERVER_ROOT_MARGIN, OBSERVER_THRESHOLD } from './constants'
+
+import './styles.scss'
+
+/**
+ * Please read
+ *   https://developer.chrome.com/docs/css-ui/sticky-headers
+ * as a reference for the implementation
+ */
+const useStickyEvent = <T extends HTMLElement = HTMLDivElement>({
+    callback,
+    containerClassName,
+    containerRef,
+    isStickyElementMounted,
+    identifier,
+}: UseStickyEventProps<T>) => {
+    const stickyElementRef = useRef<T>(null)
+
+    useEffect(
+        () => {
+            if (!stickyElementRef.current || (!isNullOrUndefined(isStickyElementMounted) && !isStickyElementMounted)) {
+                return noop
+            }
+
+            const stickyElementParent = containerRef
+                ? containerRef.current
+                : Array.from(document.getElementsByClassName(containerClassName)).find((element) =>
+                      element.contains(stickyElementRef.current),
+                  )
+
+            if (!stickyElementParent) {
+                return noop
+            }
+
+            let previousStuckState: boolean
+
+            const intersectionObserver = new IntersectionObserver(
+                (entries) => {
+                    entries.forEach((entry) => {
+                        const isStuck = !entry.isIntersecting
+                        if (isNullOrUndefined(previousStuckState) || isStuck !== previousStuckState) {
+                            callback(isStuck)
+                            previousStuckState = isStuck
+                        }
+                    })
+                },
+                { root: stickyElementParent, threshold: OBSERVER_THRESHOLD, rootMargin: OBSERVER_ROOT_MARGIN },
+            )
+
+            const sentinelId = `${identifier}__sentinel`
+
+            let sentinelElement = document.getElementById(sentinelId)
+
+            if (!sentinelElement) {
+                sentinelElement = document.createElement('div')
+                sentinelElement.id = sentinelId
+                sentinelElement.classList.add('sticky-container__sentinel')
+            }
+
+            // The sentinel element's height must exceed the sticky element's top CSS value.
+            // This guarantees that when the sticky element sticks to the container's edge,
+            // the sentinel element will extend beyond the scroll container.
+            sentinelElement.style.height =
+                window.getComputedStyle(stickyElementRef.current).top?.replace(/[0-9]+/g, (match) => {
+                    const nMatch = Number(match)
+                    if (Number.isNaN(nMatch)) {
+                        return FALLBACK_SENTINEL_HEIGHT
+                    }
+                    return `${nMatch + 1}`
+                }) ?? FALLBACK_SENTINEL_HEIGHT
+
+            stickyElementRef.current.appendChild(sentinelElement)
+
+            intersectionObserver.observe(sentinelElement)
+
+            return () => {
+                intersectionObserver.disconnect()
+            }
+        },
+        // NOTE: The isStickyElementMounted dependency ensures that this effect
+        // runs not only on mount/unmount but also when the isStickyElementMounted value changes.
+        // This is important because the sticky element might not be present during
+        // the initial render and could be added later based on certain conditions.
+        // By using isStickyElementMounted as a dependency, we make sure that the effect
+        // re-runs when the element is rendered, allowing the stickyElementRef to be populated.
+        isNullOrUndefined(isStickyElementMounted) ? [] : [isStickyElementMounted],
+    )
+
+    return { stickyElementRef }
+}
+
+export default useStickyEvent